Package Torello.Java
Class LV
- java.lang.Object
-
- Torello.Java.LV
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Cloneable
public class LV extends java.lang.Object implements java.io.Serializable, java.lang.Cloneable
The Loop-Variable End-Points class is used extensively throughout the Java-HTML Library for throwing properly formatted exception messages vis-a-vis loop variables.
This is a helper class which really, primarily, guarantees that formatted error messages will have a uniform & consistent look when thrown. This class checks that the two numbers:sPos, ePos
(which are ubiquitous in this package) are well chosenVector
indices.
If these two numbers provided are not consistent with the given the inputArray
orVector
, then anIndexOutOfBoundsException
is automatically thrown.
Ubiquitous:
The syntax for using this class is extremely simply, and found in many places throughout the Java HTML JAR Library. In the example below, it should be obvious that the Loop-Boundary End-Points chosen would cause an exception throw because they aren't within the bounds of theString[]
-Array.
Using theLV
class, this problem would be found immediately; but more importantly, a consistent exception message is automatically thrown, saving the programmer the time and headache of having to worry about writing these messges. The constructor below does the exception throw, and will provide a message that explains exactly what has gone wrong.
Example:
String[] strArr = new String[10]; // NOTE: That '15' is bout of bounds for a String-Array of Length 10 // This constructor will throw an exception before the loop is ever entered! LV l = new LV(strArr, 0, 15); // Some simply initialization loop for (int i=l.start; i < l.end; i++) strArr[i] = "Some New String";
Any class in this package that accepts the parametersint sPos, int ePos
will funnel these parameters through this 'loop-variable' class, to ensure 'fail-fast' behaviour in the search-algorithms.- See Also:
- Serialized Form
Hi-Lited Source-Code:- View Here: Torello/Java/LV.java
- Open New Browser-Tab: Torello/Java/LV.java
File Size: 24,543 Bytes Line Count: 549 '\n' Characters Found
-
-
Field Summary
Serializable ID Modifier and Type Field static long
serialVersionUID
Loop-Boundary Public, Final Fields Modifier and Type Field int
end
This integer represents the ending point of afor-loop
.int
start
This integer represents the starting point of afor-loop
.
-
Constructor Summary
Constructors Constructor Description LV(int sPos, int ePos, Object primitiveArray)
Checks input parameters and either throwsArrayIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.LV(int sPos, int ePos, Vector<?> v)
Explaining the issue of type-checking with java-generics, once a certain point has been reached, is an exercise in futility.LV(String s, int sPos, int ePos)
Checks input parameters and either throwsStringIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.LV(String s, int sPos, int ePos, int cmprStrLen)
Checks input parameters and either throwsStringIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.LV(Vector<? extends HTMLNode> html, int sPos, int ePos)
Checks input parameters and either throwsIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.LV(T[] arr, int sPos, int ePos)
Checks input parameters and either throwsArrayIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.
-
Method Summary
Methods: interface java.lang.Cloneable Modifier and Type Method LV
clone()
Java'sinterface Cloneable
requirements.Methods: class java.lang.Object Modifier and Type Method boolean
equals(Object o)
Java'spublic boolean equals(Object o)
requirements.int
hashCode()
Implements the standard java'hashCode()'
method.String
toString()
Java'stoString()
requirement.Retrieve the number of elements to be iterated by 'this' LV-instance Modifier and Type Method int
size()
Returns the number of elements that would be iterated, if using'this'
instance ofLV
as a loop-control variable.
-
-
-
Field Detail
-
serialVersionUID
public static final long serialVersionUID
This fulfils the SerialVersion UID requirement for all classes that implement Java'sinterface java.io.Serializable
. Using theSerializable
Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.- See Also:
- Constant Field Values
- Code:
- Exact Field Declaration Expression:
public static final long serialVersionUID = 1;
-
start
public final int start
This integer represents the starting point of afor-loop
. It is guaranteed to be consistent with theVector
that was used with the constructor of this class.
-
end
public final int end
This integer represents the ending point of afor-loop
. It is guaranteed to be consistent with theVector
that was used with the constructor of this class.
-
-
Constructor Detail
-
LV
public LV(java.util.Vector<? extends HTMLNode> html, int sPos, int ePos)
Checks input parameters and either throwsIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.- Parameters:
html
- This is any vectorized-html pageVector
.sPos
- This is the starting position in theVector
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in theVector
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set tohtml.size()
, otherwisethis.end
is assigned the value of'ePos'
.- Throws:
java.lang.IndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thesize
of theVector
- If
'ePos'
is zero, or greater than the size of theVector
- If the value of
'sPos'
is a larger integer than'ePos'
. If'ePos'
was negative, it is first reset toVector.size()
, before this check is done.
- If
- Code:
- Exact Constructor Body:
int size = html.size(); if ((size == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= size) throw new IndexOutOfBoundsException( "Starting Vector Position is greater than or equal to the Vector's size:\n" + NOTEV(size, sPos, ePos) ); if (sPos < 0) throw new IndexOutOfBoundsException ("Starting Vector Position is negative: " + NOTEV(size, sPos, ePos)); if (ePos > size) throw new IndexOutOfBoundsException( "Ending Vector Position is greater than the size of the Vector:\n" + NOTEV(size, sPos, ePos) ); if (ePos == 0) throw new IndexOutOfBoundsException ("Ending Vector Position is zero.:\n" + NOTEV(size, sPos, ePos)); this.start = sPos; this.end = (ePos <= 0) ? size : ePos; if (start > end) throw new IllegalArgumentException( "The starting and ending Vector Positions are not properly chosen:\n" + NOTEV(size, sPos, ePos) );
-
LV
public LV(int sPos, int ePos, java.util.Vector<?> v)
Explaining the issue of type-checking with java-generics, once a certain point has been reached, is an exercise in futility. The JDK development team did a lot of work on Java Generics, but didn't not bring them into the "Run-Time" world. As such, there are a few, details, as we shall call them with names like "CAP#1" that prevent some perfectly reasonable looking code structures that simply will not compile.
This constructor is identical to the other constructor in this class, but has had its parameter position inputs reversed in the method signature. Also, it accepts a raw-typeVector
instance. This should not present a problem to users at all, but to the developer of this project / package, it can be disconcerting. In any case, this constructor checks the input parameters and either throwsIndexOutOfBoundsException
or returns a proper loop-variable starting-ending point class-object.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.- Parameters:
v
- This may be anyraw-type Vector
.
NOTE: The symbols<?>
appended to the (almost) 'raw-type' here, are only there to prevent the java-compiler from issuing warnings regarding the use of "Raw Types." This warning is, actually, only issued if the command-line option-Xlint:all
option is used.sPos
- This is the starting position in theVector
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in theVector
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set tohtml.size()
, otherwisethis.end
is assigned the value of'ePos'
.- Throws:
java.lang.IndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thesize
of theVector
- If
'ePos'
is zero, or greater than the size of theVector
- If the value of
'sPos'
is a larger integer than'ePos'
. If'ePos'
was negative, it is first reset toVector.size()
, before this check is done.
- If
- Code:
- Exact Constructor Body:
int size = v.size(); if ((size == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= size) throw new IndexOutOfBoundsException( "Starting Vector Position is greater than or equal to the Vector's size:\n" + NOTEV(size, sPos, ePos) ); if (sPos < 0) throw new IndexOutOfBoundsException ("Starting Vector Position is negative: " + NOTEV(size, sPos, ePos)); if (ePos > size) throw new IndexOutOfBoundsException( "Ending Vector Position is greater than the size of the Vector:\n" + NOTEV(size, sPos, ePos) ); if (ePos == 0) throw new IndexOutOfBoundsException ("Ending Vector Position is zero.:\n" + NOTEV(size, sPos, ePos)); this.start = sPos; this.end = (ePos <= 0) ? size : ePos; if (start > end) throw new IllegalArgumentException( "The starting and ending Vector Positions are not properly chosen:\n" + NOTEV(size, sPos, ePos) );
-
LV
public LV(java.lang.String s, int sPos, int ePos)
Checks input parameters and either throwsStringIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.- Parameters:
s
- This may be anyString
.sPos
- This is the starting position in theString
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in theString
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set tos.size()
, otherwisethis.end
is assigned the value of'ePos'
.- Throws:
java.lang.StringIndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thelength
of theString
- If
'ePos'
is zero, or greater than the length of theString
- If the value of
'sPos'
is a larger integer than'ePos'
. IfePos
was negative, it is first reset toString.length()
, before this check is done.
- If
- Code:
- Exact Constructor Body:
int length = s.length(); if ((length == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= length) throw new StringIndexOutOfBoundsException( "Starting String Position is greater than or equal to the String's length:\n" + NOTESTR(length, sPos, ePos) ); if (sPos < 0) throw new StringIndexOutOfBoundsException ("Starting String Position is negative:\n" + NOTESTR(length, sPos, ePos)); if (ePos > length) throw new StringIndexOutOfBoundsException( "Ending String Position is greater than the length of the String:\n" + NOTESTR(length, sPos, ePos) ); if (ePos == 0) throw new StringIndexOutOfBoundsException ("Ending String Position is zero:\n" + NOTESTR(length, sPos, ePos)); this.start = sPos; this.end = (ePos <= 0) ? length : ePos; if (start > end) throw new IllegalArgumentException( "The starting and ending String positions are not properly chosen:\n" + NOTESTR(length, sPos, ePos) );
-
LV
public LV(java.lang.String s, int sPos, int ePos, int cmprStrLen)
Checks input parameters and either throwsStringIndexOutOfBoundsException
or returns proper loop-variable starting & ending values. In this constructor, the length of a second, comparing-String
, substring is expected as a parameter. This version of theLV
constructor is used byclass StrIndexOf
.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.- Parameters:
s
- This may be anyString
.sPos
- This is the starting position in theString
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in theString
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set tos.length() - cmprStrLen + 1
, otherwisethis.end
is assigned the value of'ePos'
.
MEANING: Since theString
-Search andString-Loops
should be as optimized as possible - due to the fact there is a possibility they could be invoked many, many times - Setting the value ofthis.end
to be 'less the value of a compare-String
length' means that many fewer comparison's need to be performed. The compare-String
cannot possibly fit betweenePos
and 'the end of the source-String
' ifePos
is closer to the end of the source-String
than the total size of'cmprStrLen'
. Primarily, if this does not make sense, this constructor is an optimization on the standardString
loop variable constructor that allows to shortedthis.end
in order to eliminate extraneousfor-loop
comparison's inclass StrCmpr
.cmprStrLen
- This is just an integer that represents the length of a comparisonString
. When looping through the contents of oneString
, and comparing those contents to anotherString
- the length of that secondString
should be subtracted from the value that is stored in the fieldpublic final int end
This is because oneString
cannot be a substring of another with a beginning matching index that does not accommodate a match before theString
, itself, runs out.- Throws:
java.lang.StringIndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thelength
of theString
- If
'ePos'
is zero, or greater than the length of theString
- If the value of
'sPos'
is a larger integer than'ePos'
. IfePos
was negative, it is first reset toString.length()
, before this check is done.
- If
- Code:
- Exact Constructor Body:
int length = s.length(); if ((length == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= length) throw new StringIndexOutOfBoundsException( "Starting String Position is greater than or equal to the String's length:\n" + NOTESTR(length, sPos, ePos, cmprStrLen) ); if (sPos < 0) throw new StringIndexOutOfBoundsException ("Starting String position is negative:\n" + NOTESTR(length, sPos, ePos, cmprStrLen)); if (ePos > length) throw new StringIndexOutOfBoundsException( "Ending String Position is greater than the length of the String:\n" + NOTESTR(length, sPos, ePos, cmprStrLen) ); if (ePos == 0) throw new StringIndexOutOfBoundsException ("Ending String Position is zero:\n" + NOTESTR(length, sPos, ePos, cmprStrLen)); this.start = sPos; int endTEMP = (ePos <= 0) ? length : ePos; if (start > endTEMP) throw new IllegalArgumentException( "The starting and ending String positions are not properly chosen:\n" + NOTESTR(length, sPos, ePos, cmprStrLen) ); endTEMP = endTEMP - cmprStrLen + 1; this.end = (endTEMP < sPos) ? sPos : endTEMP;
-
LV
public LV(T[] arr, int sPos, int ePos)
Checks input parameters and either throwsArrayIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.- Parameters:
arr
- This may be an array of any typeObject
sPos
- This is the starting position in the'array'
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in the'array'
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set toarray.length
, otherwisethis.end
is assigned the value of'ePos'
.- Throws:
java.lang.ArrayIndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thelength
of theArray
- If
'ePos'
is zero, or greater than the length of theArray
- If the value of
'sPos'
is a larger integer than'ePos'
. If'ePos'
was negative, it is first reset toArray.length
, before this check is done.
- If
- Code:
- Exact Constructor Body:
int length = arr.length; if ((length == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= length) throw new ArrayIndexOutOfBoundsException( "Starting Array Position is greater than or equal to the Array's length:\n" + NOTEA(length, sPos, ePos) ); if (sPos < 0) throw new ArrayIndexOutOfBoundsException ("Starting Array Position is negative: " + NOTEA(length, sPos, ePos)); if (ePos > length) throw new IndexOutOfBoundsException( "Ending Array Position is greater than the length of the Array:\n" + NOTEA(length, sPos, ePos) ); if (ePos == 0) throw new ArrayIndexOutOfBoundsException ("Ending Array Position is zero.:\n" + NOTEA(length, sPos, ePos)); this.start = sPos; this.end = (ePos <= 0) ? length : ePos; if (start > end) throw new IllegalArgumentException( "The starting and ending Array Positions are not properly chosen:\n" + NOTEA(length, sPos, ePos) );
-
LV
public LV(int sPos, int ePos, java.lang.Object primitiveArray)
Checks input parameters and either throwsArrayIndexOutOfBoundsException
or returns proper loop-variable starting & ending values.
'ePos' Negative-Value
In every situation where integer-parameters'sPos'
and'ePos'
are used, the ending-parameter'ePos'
will accept a Negative-Value. In such cases, the value that is ultimately assigned to the fieldend
will be the exact size / length of the input Data-Structure.
In this particular method, when'ePos'
is passed a Negative-Value, the length of the input-array parameter'primitiveArray'
(the value assigned toend
) is computed using a heuristic fromjava.lang.reflect
.- Parameters:
primitiveArray
- This may be an array of any primitive type.int[], float[], boolean[]
, etc...sPos
- This is the starting position in the'array'
for the loop-variable counter being created. This value is inclusive. This means that the first element searched by'this'
loop-variable counter instance shall be at the index'sPos'
.
If all validity checks are passed,'this.start'
is assigned the value of'sPos'
.ePos
- This is the ending position in the'array'
for the loop-variable counter being created. This value is exclusive. This means that the last element searched by'this'
loop-variable counter instance shall be at the indexePos - 1
.
A negative value may be passed to'ePos'
- and if so,this.end
shall be set toprimitiveArray.length
, otherwisethis.end
is assigned the value of'ePos'
.- Throws:
java.lang.ArrayIndexOutOfBoundsException
- This exception shall be thrown if any of the following are true:- If
'sPos'
is negative, or ifsPos
is greater-than-or-equal-to thelength
of theArray
- If
'ePos'
is zero, or greater than the length of theArray
- If the value of
'sPos'
is a larger integer than'ePos'
. If'ePos'
was negative, it is first reset toArray.length
, before this check is done.
- If
ArrayExpectedError
- This error is thrown if the reference passed to parameter'primitiveArray'
is not actually a reference to abyte[], short[], int[]
etc... primitive array. An error is used because the whole purpose of the classLV
is to help reduce programming errors with automatic for-loop bounds checking. If, in the course of exception checking, another exception is thrown it signals a more fundamental mistake has been made.- Code:
- Exact Constructor Body:
if (! primitiveArray.getClass().isArray()) throw new ArrayExpectedError( "The Object passed to 'primitiveArray' is not an actually an array, but " + "rather an instance of [" + primitiveArray.getClass().getName() + ']' ); int length = java.lang.reflect.Array.getLength(primitiveArray); if ((length == 0) && (sPos == 0) && (ePos <= 0)) { this.start = this.end = 0; return; } if (sPos >= length) throw new ArrayIndexOutOfBoundsException( "Starting Array Position is greater than or equal to the Array's length:\n" + NOTEA(length, sPos, ePos) ); if (sPos < 0) throw new ArrayIndexOutOfBoundsException ("Starting Array Position is negative: " + NOTEA(length, sPos, ePos)); if (ePos > length) throw new ArrayIndexOutOfBoundsException( "Ending Array Position is greater than the length of the Array:\n" + NOTEA(length, sPos, ePos) ); if (ePos == 0) throw new ArrayIndexOutOfBoundsException ("Ending Array Position is zero.:\n" + NOTEA(length, sPos, ePos)); this.start = sPos; this.end = (ePos <= 0) ? length : ePos; if (start > end) throw new IllegalArgumentException( "The starting and ending Array Positions are not properly chosen:\n" + NOTEA(length, sPos, ePos) );
-
-
Method Detail
-
hashCode
public int hashCode()
Implements the standard java'hashCode()'
method. This will provide a hash-code that is very likely to avoid crashes.- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- A hash-code that may be used for inserting
'this'
instance into a hashed table, map or list. - Code:
- Exact Method Body:
return this.start + (1000 * this.end);
-
toString
public java.lang.String toString()
Java'stoString()
requirement.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representing 'this' instance of LV / Loop-Variables.
- Code:
- Exact Method Body:
return "[Loop-Start: " + start + ", Loop-Break: " + end + "]";
-
equals
public boolean equals(java.lang.Object o)
Java'spublic boolean equals(Object o)
requirements.- Overrides:
equals
in classjava.lang.Object
- Parameters:
o
- This may be any Java Object, but only ones of'this'
type whose internal-values are identical with'this'
instance will make this method returnTRUE
.- Returns:
TRUE
if (and only if) parameter'o'
is aninstanceof LV
and, also, has equal'start'
and'end'
field values.- Code:
- Exact Method Body:
if (o instanceof LV) { LV dp = (LV) o; return (this.start == dp.start) && (this.end == dp.end); } else return false;
-
clone
public LV clone()
Java'sinterface Cloneable
requirements. This instantiates a newLV
with identical'start', 'end'
fields.- Overrides:
clone
in classjava.lang.Object
- Returns:
- A new
LV
instance whose internal fields are identical to this one. - Code:
- Exact Method Body:
return new LV(this.start, this.end);
-
size
-
-