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 142 143 144 145 146 147 | package Torello.HTML.NodeSearch; import Torello.HTML.DotPair; import java.util.Vector; /** * An exception thrown by the {@code HNLI} & {@code HNLIInclusive} iterators when, in the * processes of modifying or reading the contents of the most recent {@code Iterator}-Match, a * location is specified that's out of the bounds of the {@code Vector} itself. * * <BR /><BR /><B CLASS=JDDescLabel>Using this Exception:</B> * * <BR />The use of this exception differs slightly from that of the {@link CursorException}, with * the primary difference being that a failed cursor-operation resulting in an invalid-cursor is * not identical to an "Out of Bounds" exception for that iterator <I>(when the * <CODE>Iterator</CODE>, itself, might not have even had a cursor set by the user!)</I>. * * @see HNLIInclusive * @see HNLI */ public class IteratorOutOfBoundsException extends IndexOutOfBoundsException { /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDEX> */ public static final long serialVersionUID = 1; /** Constructs an {@code IteratorOutOfBoundsException} with no detail message. */ public IteratorOutOfBoundsException() { super(); } /** * Constructs an {@code IteratorOutOfBoundsException} with the specified detail message. * * @param message the detail message. */ public IteratorOutOfBoundsException(String message) { super(message); } /** * This method provides a consistently formatted error message when this exception is thrown by * the {@code HNLI} & {@code HNLIInclusive} {@code Iterator} classes. Mostly, like * standard {@code Vector} operations, if the {@code int 'pos'} parameter that was passed is * negative or past the end of the {@code Vector}, an {@code IndexOutOfBoundsException} will be * thrown. * * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by * an {@code HNLI} & {@code HNLIInclusive} {@code Iterator} class. * * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES> * * @param pos This is the position that has been attempted to index that {@code Vector}. * * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter * {@code 'pos'} is negative, or greater than the size of the {@code Vector} parameter * {@code 'v'}. * * @see HNLI * @see HNLIInclusive */ public static void check(Vector<?> v, int pos) { if (pos < 0) throw new IteratorOutOfBoundsException( "An attempt was made to reference the internal-state vector with a negative " + "index-value: [" + pos + "]" ); if (pos >= v.size()) throw new IteratorOutOfBoundsException( "An attempt was made to reference the internal-state vector with an index that " + "is past the end of the Vector. The attempted operation was made using " + "index [" + pos + "], but the internal-state vector has " + "vector.size() [" + v.size() + "]." ); } /** * This method provides a consistently formatted error message for this exception. This is * used by the {@code HNLI} & {@code HNLIInclusive} {@code Iterator} classes. Mostly, * like standard {@code Vector} operations, if the {@code DotPair 'dp'} provided is not * consistent with the dimensions of the input html-{@code Vector}, then an * {@code IndexOutOfBoundsException} will be thrown. * * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by * an {@code HNLI} & {@code HNLIInclusive} {@code Iterator} class. * * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES> * * @param dp This is the sub-section, or sub-list of the {@code Vector} that is being checked. * * @throws IteratorOutOfBoundsException This will throw if the value passed to parameter * {@code 'dp'} is negative, or greater than the size of {@code Vector} parameter * {@code 'v'}. * * @see HNLI * @see HNLIInclusive */ public static void check(Vector<?> v, DotPair dp) { if (dp.end >= v.size()) throw new IteratorOutOfBoundsException( "An attempt was made to reference the internal-state vector with an index that " + "is past the end of the Vector. The attempted operation was made using " + "DotPair " + dp.toString() + ", but the internal-state vector has " + "vector.size() [" + v.size() + "]." ); } /** * This method provides a consistently formatted error message when this exception is thrown by * the {@code HNLI} & {@code HNLIInclusive} {@code Iterator} classes. Mostly, like * standard {@code Vector} operations, if any of the index-positions that are referenced by the * {@code int[] posArr} parameter are negative or past the end of the {@code Vector}, an * {@code IndexOutOfBoundsException} will be thrown. * * @param v This is usually passed a reference to the internal {@code Raw-Type Vector} used by * an {@code HNLI} & {@code HNLIInclusive} {@code Iterator} class. * * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES> * * @param posArr This is the {@code array} of position-indices into {@code Vector} parameter * {@code 'v'} that have been requested to update or for replacement. * * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT:</B></SPAN> In the code that invokes this * method, the {@code int[]} position-{@code array} passed to parameter {@code 'posArr'} will * <B><I>ALWAYS</I></B> have been sorted before being received here. As such, only the first * and last elements of this array are actually check for validity. If this {@code array} is * not sorted, then the check performed by this method will be thoroughly insufficient. * * @throws IteratorOutOfBoundsException This will throw if any of the the values passed to * parameter {@code 'posArr'} are negative, or greater than the size of {@code Vector} * parameter {@code 'v'}. * * @see HNLI * @see HNLIInclusive */ public static void check(Vector<?> v, int[] posArr) { if (posArr[0] < 0) throw new IteratorOutOfBoundsException( "An attempt was made to reference the internal-state vector with a " + "negative index-value. The smallest (most-negative) value " + "passed to the vector-index integer-array was [" + posArr[0] + "]." ); if (posArr[posArr.length-1] >= v.size()) throw new IteratorOutOfBoundsException( "An attempt was made to reference the internal-state vector with a " + "location that is past the end of the Vector. The largest value passed to " + "the vector-index integer-array was [" + posArr[posArr.length-1] + "]. " + "The internal-state vector has vector.size() [" + v.size() + "]." ); } } |