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
    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 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


    • 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 a for-loop.
      int start
      This integer represents the starting point of a for-loop.
    • Constructor Summary

      Constructors 
      Constructor Description
      LV​(int sPos, int ePos, Object primitiveArray)
      Checks input parameters and either throws ArrayIndexOutOfBoundsException 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 throws StringIndexOutOfBoundsException or returns proper loop-variable starting & ending values.
      LV​(String s, int sPos, int ePos, int cmprStrLen)
      Checks input parameters and either throws StringIndexOutOfBoundsException or returns proper loop-variable starting & ending values.
      LV​(Vector<? extends HTMLNode> html, int sPos, int ePos)
      Checks input parameters and either throws IndexOutOfBoundsException or returns proper loop-variable starting & ending values.
      LV​(T[] arr, int sPos, int ePos)
      Checks input parameters and either throws ArrayIndexOutOfBoundsException or returns proper loop-variable starting & ending values.
    • Method Summary

       
      Methods: interface java.lang.Cloneable
      Modifier and Type Method
      LV clone()
      Java's interface Cloneable requirements.
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      Java's public boolean equals(Object o) requirements.
      int hashCode()
      Implements the standard java 'hashCode()' method.
      String toString()
      Java's toString() requirement.
       
      Retrieve the number of elements to be iterated by 'this' LV
      Modifier and Type Method
      int size()
      Returns the number of elements that would be iterated, if using 'this' instance of LV as a loop-control variable.
      • Methods inherited from class java.lang.Object

        finalize, getClass, notify, notifyAll, wait, wait, wait
    • 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:
        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:
        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:
        public final int end;
        
    • Constructor Detail

      • LV

        🡅  🡇    
        public LV​(java.util.Vector<? extends HTMLNode> html,
                  int sPos,
                  int ePos)
        Checks input parameters and either throws IndexOutOfBoundsException or returns proper loop-variable starting & ending values.

        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.
        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-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.
        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 throws StringIndexOutOfBoundsException or returns proper loop-variable starting & ending values.

        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.
        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 throws StringIndexOutOfBoundsException 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 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.
        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 throws ArrayIndexOutOfBoundsException or returns proper loop-variable starting & ending values.

        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.
        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 throws ArrayIndexOutOfBoundsException or returns proper loop-variable starting & ending values.

        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.
        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 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:
         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:
         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:
         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:
         return new LV(this.start, this.end);
        
      • size

        🡅    
        public int size()
        Returns the number of elements that would be iterated, if using 'this' instance of LV as a loop-control variable.
        Returns:
        The number of element's that are referenced by 'this' instance.
        See Also:
        start, end
        Code:
        Exact Method Body:
         return end - start;