001package Torello.Java;
002
003import java.util.Vector;
004
005/**
006 * Throws when a Method's (or Constructor's) integer-valued parameter <I>(often for parameters that
007 * are actually named <CODE>'n'</CODE>, representing a 'count' of some form or fasion)</I> does not
008 * adhere to some of those Method's expectations or requirements.
009 * 
010 * This exception is used, extensively, by the classes {@link StrIndexOf} and {@link StrTokIndexOf}
011 * inside all methods where an integer parameter {@code 'n'} is required.  (These methods all have
012 * names that begin with the three letters {@code 'nth'}).  If an inappropriate value for
013 * {@code 'n'} is passed - <I>for instance a negative value</I> - then this exception will throw.
014 * The value of {@code 'n'} refers to the nth-instance of a substring or character, and thusly,
015 * negative-values are meaningless.
016 * 
017 * <BR /><BR />This exception is also used in the {@code package HTML.NodeSearch}, for the exact
018 * same purpose, but applied to HTML {@code Vector} match-counts, rather than sub-{@code String}
019 * match-counts.
020 */
021public class NException extends IndexOutOfBoundsException
022{
023    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX>  */
024    public static final long serialVersionUID = 1;
025
026    /** Constructs an {@code NException} with no detail message. */
027    public NException()
028    { super(); }
029
030    /**
031     * Constructs an {@code NException} with the specified detail message.
032     * @param message the detail message.
033     */
034    public NException(String message)
035    { super(message); }
036
037    /**
038     * Constructs a new exception with the specified detail {@code 'message'} and 
039     * {@code 'cause'}.
040     * 
041     * <BR /><BR /><B CLASS=JDDescLabel>NOTE:</B>
042     * 
043     * <BR /><BR />The detail message associated with cause is not automatically incorporated into
044     * this exception's detail message.
045     * 
046     * @param message The detail message (which is saved for later retrieval by th
047     * {@code Throwable.getMessage()} method).
048     * 
049     * @param cause the cause (which is saved for later retrieval by the
050     * {@code Throwable.getCause()} method). (A null value is permitted, and indicates that the
051     * cause is nonexistent or unknown.)
052     */
053    public NException(String message, Throwable cause)
054    { super(message); initCause(cause); }
055
056    /**
057     * Constructs a new exception with the specified {@code 'cause'} and a detail message of
058     * {@code (cause==null ? null : cause.toString())} (which typically contains the class
059     * and detail message of cause).  This constructor is useful for exceptions that are little
060     * more than wrappers for other throwables.
061     * 
062     * @param cause The cause (which is saved for later retrieval by the
063     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
064     * cause is nonexistent or unknown.)
065     */
066    public NException(Throwable cause)
067    { super(); initCause(cause); }
068
069    /**
070     * Constructs a new NException with an argument indicating the value of {@code 'n'} was the
071     * problem for a message.  This is the internally used constructor.
072     * 
073     * @param n This is just the value of {@code 'n'} that was passed, and caused the exception.
074     */
075    public NException(int n)
076    {
077        super(
078            "The value of n [" + n + "] you have passed is not allowed.  It must be " + 
079            "a positive integer, and less than the compare string length."
080        );
081    }
082
083    /**
084     * This will check a value of of parameter {@code 'n'} against a {@code java.lang.String}, for
085     * the purposes of {@code String}-Comparison Routines.
086     * 
087     * @param n This is the value of {@code 'n'} to check
088     * 
089     * @param s This parameter is the {@code String} against which the index-of operation is being
090     * performed.
091     * 
092     * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the length of the
093     * {@code String}.
094     */
095    public static void check(int n, String s)
096    {
097        if (n < 1) throw new NException(n);
098
099        if (n > s.length()) throw new NException(
100            "The value passed to parameter 'n' [" + n + "] is greater than the compare-string length " +
101            "[" + s.length() + "]"
102        );
103    }
104
105    /**
106     * This will check a value of of parameter {@code 'n'} against a {@code Vector}, for the
107     * purposes of {@code Vector}-Search Routines.
108     * 
109     * @param n This is the value of {@code 'n'} to check
110     * 
111     * @param v This parameter is the {@code Vector} against which the index-of operation is being
112     * performed.
113     * 
114     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
115     * 
116     * @throws NException if {@code 'n'} is less than {@code 1}, or greater than the size of the
117     * {@code Vector}.
118     */
119    public static void check(int n, Vector<?> v)
120    {
121        if (n < 1) throw new NException(n);
122
123        if (n > v.size()) throw new NException(
124            "The value passed to parameter 'n' [" + n + "] is greater than the vector size " +
125            "[" + v.size() + "]"
126        );
127    }
128
129    /**
130     * This will check a value of of parameter {@code 'n'} to ensure that it is a positive-Integer
131     * (greater-than zero).
132     * 
133     * @param n This is the value of {@code n} to check
134     * 
135     * @throws NException if {@code 'n'} is less than {@code 1}.
136     */
137    public static void check(int n)
138    {
139        if (n < 0)  throw new NException(
140            "A negative value has been passed to parameter 'n' [" + n + "], but " +
141            "this is not allowed here."
142        );
143
144        if (n == 0) throw new NException
145            ("Zero was passed to parameter 'n', but this is not allowed here.");
146    }
147
148}