1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
package Torello.Java;

import java.util.Vector;

/**
 * <CODE>NException - Documentation.</CODE><BR /><BR />
 * 
 * This exception is used by {@code class StrIndexOf} in all of the methods in which a
 * {@code int n} is required.  These are the methods whose names begins with the 3-letter
 * {@code 'nth'}.  If an inappropriate value for {@code int n} is passed, then this exception will
 * throw.  Since the value of {@code 'n'} refers to the nth-instance of a substring or character.
 * This exception is also used in the {@code package HTML.NodeSearch}, for the exact same purpose,
 * but applied to HTML {@code Vector's}.
 */
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>NOTE:</B> The detail message associated with {@code 'cause'} is not
     * automatically  incorporated in 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.");
    }

}