Package Torello.Java

Class LV

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

    public class LV
    extends java.lang.Object
    implements java.io.Serializable, java.lang.Cloneable
    LV (Loop-Variable End-Points) - Documentation.

    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 two numbers: sPos, ePos (which are ubiquitous in this package) are well chosen vector-index values. If these are not properly chosen for-loop(int sPos; expr(ePos);) integers, then this class, during instantiation / construction, will immediately throw an IndexOutOfBoundsException. Any class in this package that accepts the parameters int 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



    • Constructor Summary

      Constructors 
      Constructor
      LV​(int sPos, int ePos, Object primitiveArray)
      LV​(int sPos, int ePos, Vector<?> v)
      LV​(String s, int sPos, int ePos)
      LV​(String s, int sPos, int ePos, int cmprStrLen)
      LV​(Vector<? extends HTMLNode> html, int sPos, int ePos)
      LV​(T[] arr, int sPos, int ePos)
    • Field Detail

      • serialVersionUID

        public static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable 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:
        1
        public static final long serialVersionUID = 1;
        
      • start

        public final int start
        This integer represents the starting point of a for-loop. It is guaranteed to be consistent with the Vector that was used with the constructor of this class.
        Code:
        Exact Field Declaration Expression:
        1
        public final int start;
        
      • end

        public final int end
        This integer represents the ending point of a for-loop. It is guaranteed to be consistent with the Vector that was used with the constructor of this class.
        Code:
        Exact Field Declaration Expression:
        1
        public final int end;
        
    • Constructor Detail

      • LV

        public LV​(java.util.Vector<? extends HTMLNode> html,
                  int sPos,
                  int ePos)
        This constructor checks the input parameters and either throws IndexOutOfBoundsException or returns a proper loop-variable starting-ending point class-object.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure.
        Parameters:
        html - This is any vectorized-html page Vector.
        sPos - This is the starting position in the Vector 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 Vector 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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to html.size(), otherwise this.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 if sPos is greater-than-or-equal-to the size of the Vector
        • If 'ePos' is zero, or greater than the size of the Vector
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.
      • 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-type Vector 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 throws IndexOutOfBoundsException or returns a proper loop-variable starting-ending point class-object.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure.
        Parameters:
        v - This may be any raw-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 the Vector 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 Vector 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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to html.size(), otherwise this.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 if sPos is greater-than-or-equal-to the size of the Vector
        • If 'ePos' is zero, or greater than the size of the Vector
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Vector.size(), before this check is done.
      • LV

        public LV​(java.lang.String s,
                  int sPos,
                  int ePos)
        This constructor checks the input parameters and either throws StringIndexOutOfBoundsException or returns a proper loop-variable starting-ending point instance.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure.
        Parameters:
        s - This may be any String.
        sPos - This is the starting position in the String 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 String 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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to s.size(), otherwise this.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 if sPos is greater-than-or-equal-to the length of the String
        • If 'ePos' is zero, or greater than the length of the String
        • If the value of 'sPos' is a larger integer than 'ePos'. If ePos was negative, it is first reset to String.length(), before this check is done.
      • LV

        public LV​(java.lang.String s,
                  int sPos,
                  int ePos,
                  int cmprStrLen)
        This constructor checks the input parameters and either throws StringIndexOutOfBoundsException or returns a proper loop-variable starting-ending point instance. In this case, the length of a second, comparing-string, substring is expected as a parameter. This version of the LV constructor is used by class StrIndexOf.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure.
        Parameters:
        s - This may be any String.
        sPos - This is the starting position in the String 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 String 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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to s.length() - cmprStrLen + 1, otherwise this.end is assigned the value of 'ePos'.

        MEANING: Since the String-Search and String-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 of this.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 between ePos and 'the end of the source-String' if ePos 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 standard String loop variable constructor that allows to shorted this.end in order to eliminate extraneous for-loop comparison's in class StrCmpr.
        cmprStrLen - This is just an integer that represents the length of a comparison String. When looping through the contents of one String, and comparing those contents to another String - the length of that second String should be subtracted from the value that is stored in the field public final int end This is because one String cannot be a substring of another with a beginning matching index that does not accommodate a match before the String, itself, runs out.
        Throws:
        java.lang.StringIndexOutOfBoundsException - This exception shall be thrown if any of the following are true:

        • If 'sPos' is negative, or if sPos is greater-than-or-equal-to the length of the String
        • If 'ePos' is zero, or greater than the length of the String
        • If the value of 'sPos' is a larger integer than 'ePos'. If ePos was negative, it is first reset to String.length(), before this check is done.
      • LV

        public LV​(T[] arr,
                  int sPos,
                  int ePos)
        This constructor checks the input parameters and either throws ArrayIndexOutOfBoundsException or returns a proper loop-variable starting-ending point class-object.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure.
        Parameters:
        arr - This may be an array of any type Object
        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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to array.length, otherwise this.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 if sPos is greater-than-or-equal-to the length of the Array
        • If 'ePos' is zero, or greater than the length of the Array
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Array.length, before this check is done.
      • LV

        public LV​(int sPos,
                  int ePos,
                  java.lang.Object primitiveArray)
        This constructor checks the input parameters and either throws ArrayIndexOutOfBoundsException or returns a proper loop-variable starting-ending point class-object.

        IMPORTANT In every situation where the parameters int sPos, int ePos are used, parameter 'ePos' will accept a negative value, but parameter 'sPos' will not. When 'ePos' is passed negative-value, the value that is ultimately assigned to public final int end will be the exact size / length of the input data-structure. *

        NOTE: The array length is extracted using a method found in package java.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 index ePos - 1.

        A negative value may be passed to 'ePos' - and if so, this.end shall be set to primitiveArray.length, otherwise this.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 if sPos is greater-than-or-equal-to the length of the Array
        • If 'ePos' is zero, or greater than the length of the Array
        • If the value of 'sPos' is a larger integer than 'ePos'. If 'ePos' was negative, it is first reset to Array.length, before this check is done.
        ArrayExpectedError - This error is thrown if the reference passed to parameter 'primitiveArray' is not actually a reference to a byte[], short[], int[] etc... primitive array. An error is used because the whole purpose of the class LV 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.
    • 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 class java.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:
        1
         return this.start + (1000 * this.end);
        
      • toString

        public java.lang.String toString()
        Java's toString() requirement.
        Overrides:
        toString in class java.lang.Object
        Returns:
        A string representing 'this' instance of LV / Loop-Variables.
        Code:
        Exact Method Body:
        1
         return "[Loop-Start: " + start + ", Loop-Break: " + end + "]";
        
      • equals

        public boolean equals​(java.lang.Object o)
        Java's public boolean equals(Object o) requirements.
        Overrides:
        equals in class java.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 return TRUE.
        Returns:
        TRUE if (and only if) parameter 'o' is an instanceof LV and, also, has equal 'start' and 'end' field values.
        Code:
        Exact Method Body:
        1
        2
        3
        4
        5
        6
         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's interface Cloneable requirements. This instantiates a new LV with identical 'start', 'end' fields.
        Overrides:
        clone in class java.lang.Object
        Returns:
        A new LV instance whose internal fields are identical to this one.
        Code:
        Exact Method Body:
        1
         return new LV(this.start, this.end);