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