package Torello.Java;

import java.util.Vector;

/**
 * Throws when a Method's (or Constructor's) integer-valued parameter <I>(often for parameters that
 * are actually named <CODE>'n'</CODE>, representing a 'count' of some form or fasion)</I> does not
 * adhere to some of those Method's expectations or requirements.
 * 
 * This exception is used, extensively, by the classes {@link StrIndexOf} and {@link StrTokIndexOf}
 * inside all methods where an integer parameter {@code 'n'} is required.  (These methods all have
 * names that begin with the three letters {@code 'nth'}).  If an inappropriate value for
 * {@code 'n'} is passed - <I>for instance a negative value</I> - then this exception will throw.
 * The value of {@code 'n'} refers to the nth-instance of a substring or character, and thusly,
 * negative-values are meaningless.
 * 
 * <BR /><BR />This exception is also used in the {@code package HTML.NodeSearch}, for the exact
 * same purpose, but applied to HTML {@code Vector} match-counts, rather than sub-{@code String}
 * match-counts.
 */
public class NException extends IndexOutOfBoundsException
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
    public static final long serialVersionUID = 1;

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

    /**
     * Constructs an {@code NException} with the specified detail message.
     * @param message the detail message.
     */
    public NException(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 NException(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 NException(Throwable cause)
    { super(); initCause(cause); }

    /**
     * Constructs a new NException with an argument indicating the value of {@code 'n'} was the
     * problem for a message.  This is the internally used constructor.
     * 
     * @param n This is just the value of {@code 'n'} that was passed, and caused the exception.
     */
    public NException(int n)
    {
        super(
            "The value of n [" + n + "] you have passed is not allowed.  It must be " + 
            "a positive integer, and less than the compare string length."
        );
    }

    /**
     * This will check a value of of parameter {@code 'n'} against a {@code java.lang.String}, for
     * the purposes of {@code String}-Comparison Routines.
     * 
     * @param n This is the value of {@code 'n'} to check
     * 
     * @param s This parameter is the {@code String} against which the index-of operation is being
     * performed.
     * 
     * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the length of the
     * {@code String}.
     */
    public static void check(int n, String s)
    {
        if (n < 1) throw new NException(n);

        if (n > s.length()) throw new NException(
            "The value passed to parameter 'n' [" + n + "] is greater than the compare-string length " +
            "[" + s.length() + "]"
        );
    }

    /**
     * This will check a value of of parameter {@code 'n'} against a {@code Vector}, for the
     * purposes of {@code Vector}-Search Routines.
     * 
     * @param n This is the value of {@code 'n'} to check
     * 
     * @param v This parameter is the {@code Vector} against which the index-of operation is being
     * performed.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     * 
     * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the size of the
     * {@code Vector}.
     */
    public static void check(int n, Vector<?> v)
    {
        if (n < 1) throw new NException(n);

        if (n > v.size()) throw new NException(
            "The value passed to parameter 'n' [" + n + "] is greater than the vector size " +
            "[" + v.size() + "]"
        );
    }

    /**
     * This will check a value of of parameter {@code 'n'} to ensure that it is a positive-Integer
     * (greater-than zero).
     * 
     * @param n This is the value of {@code n} to check
     * 
     * @throws NException if {@code 'n'} is less than {@code 1}.
     */
    public static void check(int n)
    {
        if (n < 0)  throw new NException(
            "A negative value has been passed to parameter 'n' [" + n + "], but " +
            "this is not allowed here."
        );

        if (n == 0) throw new NException
            ("Zero was passed to parameter 'n', but this is not allowed here.");
    }

}