package Torello.Java;

import java.util.Vector;
import java.util.function.*;
import java.lang.reflect.Array;

/**
 * This may be used to check that array have equal lengths - if two or more arrays are expected to
 * be parallel, but their lengths are not equal, then this exception should be thrown.  This class
 * also provides multiple <CODE>'check'</CODE> methods that will automatically scan for the
 * specific error cases, and it will provide consistently worded and formatted error messages to
 * the invoking code.
 * 
 * <BR /><BR />Note that you may also request that the checker look for nulls, and throw a
 * {@code NullPointerException} if nulls are found.  Furthermore, primitive-arrays may also be 
 * checked.
 */
public class ParallelArrayException extends IllegalArgumentException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

    /** Constructs a {@code ParallelArrayException} with no detail message. */
    public ParallelArrayException()
    { super(); }

    /**
     * Constructs an {@code ParallelArrayException} with the specified detail message.
     * @param message the detail message.
     */
    public ParallelArrayException(String message)
    { super(message); }

    /**
     * Constructs a new exception with the specified detail {@code 'message'} and 
     * {@code 'cause'}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
     * 
     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
     * this exception's detail message.
     * 
     * @param message The detail message (which is saved for later retrieval by th
     * {@code Throwable.getMessage()} method).
     * 
     * @param cause the cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public ParallelArrayException(String message, Throwable cause)
    { super(message); initCause(cause); }

    /**
     * Constructs a new exception with the specified {@code 'cause'} and a detail message of
     * {@code (cause==null ? null : cause.toString())} (which typically contains the class
     * and detail message of cause).  This constructor is useful for exceptions that are little
     * more than wrappers for other throwables.
     * 
     * @param cause The cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public ParallelArrayException(Throwable cause)
    { super(); initCause(cause); }

    // If the array itself was a null pointer, this is all you can do
    private static void NPE(String name)
    { throw new NullPointerException("Array '" + name + "' was passed a Null Pointer."); }

    // This ensures that the error messages all look the same (same text), and that I don't
    // retype this many times.
    private static void CHECK(
            Object tArr, int tLen, String tName,
            Object uArr, int uLen, String uName
        )
    {
        if (tLen != uLen) throw new ParallelArrayException(
            "The length of Array '" + tName + "' (" + tArr.getClass().getSimpleName() + ") " +
            "is " + tLen + "\n" +
            "The length of Array '" + uName + "' (" + uArr.getClass().getSimpleName() + ") " +
            "is " + uLen + "\n" +
            "Unfortunately, these arrays must be parallel, and thus their lengths must be equal."
        );
    }

    /**
     * This will check that the parameter {@code 'arr1'} (which is presumed to be an array) has
     * an identical length to that of parameter {@code 'arr2'}.  If these two arrays do not have
     * the same length, a {@code ParallelArrayException} with throw with an error message.
     * 
     * <BR /><BR />Since the purpose of this code is to generate reasonable error messages, without
     * having to retype this sort of thing of and again, the 'Variable Name' of the arrays are
     * required as parameters.  The only effects that they have on this code is that they ensure
     * <I>the output exception messages include those names</I>  (The array names are not part of
     * the error checking process).
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
     * 
     * <BR />If for whatever reason, the caller of this method accidentally sends an {@code Object}
     * to this method which isn't an {@code Array} at all, an exception will throw.  There isn't
     * really a way to guarantee "Compile Time Checking" for this sort of thing.  Make sure this
     * method is for checking that <I><B>Array's are Parallel</I></B>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>FINALLY:</B>
     * 
     * <BR />Just about any type of array may be passed - including {@code primitive-arrays}
     * ({@code int[], float[]}) etc...
     * 
     * <BR /><BR />The method {@link StrReplace#r(String, char[], char[])} makes use of this check
     * as follows:
     * 
     * <DIV CLASS=EXAMPLE>{@code 
     * public static String r(String s, char[] matchChars, char[] replaceChars)
     * {
     *      // Check that these arrays have equal lengths, and if not throw the 
     *      // ParallelArrayException.
     *      ParallelArrayException.check(matchChars, "matchChars", replaceChars, "replaceChars");
     *      ...
     * }
     * }</DIV>
     *
     * @param arr1 This may be any primitive or {@code Object[]} array.
     * 
     * @param arr1Name This should be the 'Variable Name' of that array, in your code.  This is
     * merely used for 'Pretty Printing' purposes.
     * 
     * @param arr2 This may be any other primitive or {@code Object[]} array.
     * 
     * @param arr2Name This should be the 'Variable Name' of the second array.
     * 
     * @throws ParallelArrayException This exception throws if the arrays don't have equal 
     * lengths.
     * 
     * @throws ArrayExpectedError If a non-Array {@code Object} is passed to either of the
     * Array Parameters.  An {@code 'Error'} is thrown, rather than an {@code 'Exception'} since
     * the purpose of this check is to identify parallel arrays.  Providing a non-array reference
     * to this method signals a flaw in the code itself.
     */
    public static void check
        (Object arr1, String arr1Name, Object arr2, String arr2Name)
    {
        if (arr1 == null) NPE(arr1Name);
        if (arr2 == null) NPE(arr2Name);

        if (! arr1.getClass().isArray()) throw new ArrayExpectedError
            ("Array Parameter '" + arr1Name + "' is not an array.");

        if (! arr2.getClass().isArray()) throw new ArrayExpectedError
            ("Array Parameter '" + arr2Name + "' is not an array.");
        
        CHECK(
            arr1, java.lang.reflect.Array.getLength(arr1), arr1Name,
            arr2, java.lang.reflect.Array.getLength(arr2), arr2Name
        );
    }

    /**
     * This will check that the parameter {@code 'tArr'} has an identical length to that of
     * parameter {@code 'arr'} (which is presumed to be an array).  If these two arrays do not have
     * the same length, a {@code ParallelArrayException} with throw with an error message.
     * 
     * <BR /><BR />This method differs from the previous
     * {@link #check(Object, String, Object, String)}, in that the Variable-Type Parameter
     * {@code '<T>'} guarantees that at least one of the parameters must be an array.  This 
     * facilitates another check - that for nulls in the array.  It may or may not be desired to
     * check for the prescense of {@code 'null'}, but if it is that can be requested by passing 
     * {@code 'TRUE'} to the parameter {@code 'throwIfHasNulls'}.
     * 
     * <BR /><BR />The {@link StrReplace#r(boolean, String, String[], char[])} utilizes this method
     * as below:
     * 
     * <DIV CLASS=EXAMPLE>{@code 
     * public static String r
     *      (boolean ignoreCase, String s, String[] matchStrs, char[] replaceChars)
     * {
     *      // Make sure the 'matchStrs' array is parallel to 'replaceChars', and also make sure
     *      // 'matchStr' does not have null elements.  If not, throw ParallelArrayException
     *      ParallelArrayException.check
     *          (matchStrs, "matchStrs", true, replaceChars, "replaceChars");
     *      ...
     * }
     * }</DIV>
     *
     * @param <T> This type-parameter is merely being utilized to allow <I>any array type</I>
     * to be received by this method.  It is nothing more than a place-holder (similar to the
     * {@code '?'} for generic classes).
     * 
     * @param tArr This may be any {@code Object[]} instance array.
     * 
     * @param tName This should be the 'Variable Name' of that array, in your code.  This is
     * merely used for 'Pretty Printing' purposes.
     * 
     * @param throwIfHasNulls This parameter requests to check for the presence of a {@code 'null'}
     * inside the {@code 'tArr'} array, and will throw a {@code NullPointerException} is one is
     * found.
     * 
     * @param arr This may be any primitive or {@code Object[]} array.
     * 
     * @param arrName This should be the 'Variable Name' of the second array.
     * 
     * @throws ParallelArrayException This exception throws if the arrays don't have equal 
     * lengths.
     * 
     * @throws NullPointerException This exception throws if the {@code 'tArr'} contains any
     * {@code 'null'} values.
     * 
     * @throws ArrayExpectedError If a non-Array {@code Object} is passed to either of the
     * Array Parameters.  An {@code 'Error'} is thrown, rather than an {@code 'Exception'} since
     * the purpose of this check is to identify parallel arrays.  Providing a non-array reference
     * to this method signals a flaw in the code itself.
     */
    public static <T> void check(
            T[] tArr, String tName, boolean throwIfHasNulls,
            Object arr, String arrName
        )
    {
        if (tArr == null)   NPE(tName);
        if (arr == null)    NPE(arrName);

        if (! arr.getClass().isArray()) throw new ArrayExpectedError
            ("Array Parameter '" + arrName + "' is not an array.");

        CHECK(tArr, tArr.length, tName, arr, Array.getLength(arr), arrName);

        if (throwIfHasNulls)
            for (int i=0; i < tArr.length; i++)
                if (tArr[i] == null)
                    throw new NullPointerException(
                        tName + '[' + i + "] (" + tArr.getClass().getSimpleName() + ") " +
                        "contains a null reference."
                    );
    }

    /**
     * This will check that the parameter {@code 'tArr'} has an identical length to that of
     * parameter {@code 'arr'} (which is presumed to be an array).  If these two arrays do not have
     * the same length, a {@code ParallelArrayException} with throw with an error message.
     * 
     * <BR /><BR />This method differs from the previous
     * {@link #check(Object, String, Object, String)}, in that using Variable-Type Parameters
     * ({@code '<T>'} and {@code '<U>'}) guarantee that both parameters are arrays.  The purpose 
     * here is that it facilitates another check - that for the presence of {@code 'nulls'}.  It 
     * may or may not be desired to check for the prescense of {@code 'null'} within the arrays,
     * but if it is, simply pass {@code 'TRUE'} to either of the {@code 'throwIfHasNulls'}
     * parameters, and the corresponding array will be checked.
     * 
     * <BR /><BR />This check is used by {@link StrReplace#r(boolean, String, String[], String[])}
     * as below:
     * 
     * <DIV CLASS=EXAMPLE>{@code 
     * public static String r
     *      (boolean ignoreCase, String s, String[] matchStrs, String[] replaceStrs)
     * {
     *      // Make sure these arrays are parallel, and if not throw ParallelArrayException
     *      // If there are any 'null' values in these arrays, throw NullPointerException
     *      ParallelArrayException.check
     *          (matchStrs, "matchStrs", true, replaceStrs, "replaceStrs", true);
     *      ...
     * }
     * }</DIV>
     *
     * @param <T> This type-parameter is merely being utilized to allow <I>any array type</I>
     * to be received by this method.  It is nothing more than a place-holder (similar to the
     * {@code '?'} for generic classes).
     *
     * @param <U> This type-parameter is merely being utilized to allow <I>any array type</I>
     * to be received by this method.  It is nothing more than a place-holder (similar to the
     * {@code '?'} for generic classes).
     *
     * @param tArr This may be any {@code Object[]} instance array.
     * 
     * @param tName This should be the 'Variable Name' of that array, in your code.  This is
     * merely used for 'Pretty Printing' purposes.
     * 
     * @param throwIfTHasNulls This parameter requests to check for the presence of a
     * {@code 'null'} inside the {@code 'tArr'} array, and will throw a
     * {@code NullPointerException} is one is found.
     *
     * @param uArr This may be any {@code Object[]} instance array.
     * 
     * @param uName This should be the 'Variable Name' of that array, in your code.  This is
     * merely used for 'Pretty Printing' purposes.
     * 
     * @param throwIfUHasNulls This parameter requests to check for the presence of a
     * {@code 'null'} inside the {@code 'uArr'} array, and will throw a
     * {@code NullPointerException} is one is found.
     * 
     * @throws ParallelArrayException This exception throws if the arrays don't have equal 
     * lengths.
     * 
     * @throws NullPointerException This exception throws if the {@code 'tArr'} contains any
     * {@code 'null'} values.
     */
    public static <T, U> void check(
            T[] tArr, String tName, boolean throwIfTHasNulls,
            U[] uArr, String uName, boolean throwIfUHasNulls
        )
    {
        if (tArr == null) NPE(tName);
        if (uArr == null) NPE(uName);

        CHECK(tArr, tArr.length, tName, uArr, uArr.length, uName);

        if (throwIfTHasNulls)
            for (int i=0; i < tArr.length; i++)
                if (tArr[i] == null)
                    throw new NullPointerException(
                        tName + '[' + i + "] (" + tArr.getClass().getSimpleName() + ") " +
                        "contains a null reference."
                    );

        if (throwIfUHasNulls)
            for (int i=0; i < uArr.length; i++)
                if (uArr[i] == null)
                    throw new NullPointerException(
                        uName + "[" + i + "] (" + uArr.getClass().getSimpleName() + ") " +
                        "contains a null reference."
                    );
    }
}