Package Torello.Java

Class StringParse


  • public class StringParse
    extends java.lang.Object
    A plethora of extensions to Java's String class.

    These are some commonly used helper functions that were utilized when the project began. As the project grows more java.lang.String Utilities are added, here and there. Likely, there are probably methods that exist in libraries available somewhere in someone else' jar files. Possibly Apache Commons has a method similar to StringParse.leftSpacePad(...) - but since the complete set of Helper Utilities that are provided in package Torello.Java.*; are very detailed and numerous, home grown helper and utility functions are used, rather than trying to figure out Apache, or other's jar-libraries. Quite a number of these really just seem like naming conventions for properly formatted dates and times that avoid getting too complicated with Java's class 'Calendar' or Java's java.text.* package.


Stateless Class: This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member field. It is very similar to the Java-Bean @Stateless Annotation.
  • 1 Constructor(s), 1 declared private, zero-argument constructor
  • 92 Method(s), 92 declared static
  • 26 Field(s), 26 declared static, 26 declared final


    • Field Detail

      • WHITE_SPACE_REGEX

        🡇    
        public static final java.util.regex.Pattern WHITE_SPACE_REGEX
        This regular expression simply matches white-space found in a java String.
        See Also:
        removeWhiteSpace(String)
        Code:
        Exact Field Declaration Expression:
        public static final Pattern WHITE_SPACE_REGEX = Pattern.compile("\\s+");
        
      • NUMBER_COMMMA_REGEX

        🡅  🡇    
        public static final java.util.regex.Pattern NUMBER_COMMMA_REGEX
        This regular expression is used for integer and floating-point numbers that use the comma (',') between the digits that comprise the number. For example, this Regular Expression would match the String "900,800,75.00".
        See Also:
        FileRW.readIntsFromFile(String, boolean, boolean, int)
        Code:
        Exact Field Declaration Expression:
        public static final Pattern NUMBER_COMMMA_REGEX = Pattern.compile("(\\d),(\\d)");
        
      • NEWLINEP

        🡅  🡇    
        public static final java.util.regex.Pattern NEWLINEP
        This represents any version of the new-line character. Note that the '\r\n' version comes before the single '\r' version in the regular-expression, to guarantee that if both are present, they are treated as a single newline.
        Code:
        Exact Field Declaration Expression:
        public static final Pattern NEWLINEP = Pattern.compile("\\r\\n|\\r|\\n");
        
      • newLinePred

        🡅  🡇    
        public static final java.util.function.Predicate<java.lang.String> newLinePred
        Predicate for new-line characters
        See Also:
        NEWLINEP
        Code:
        Exact Field Declaration Expression:
        public static final Predicate<String> newLinePred = NEWLINEP.asPredicate();
        
      • GENERIC_PARAMS

        🡅  🡇    
        public static final java.util.regex.Pattern GENERIC_PARAMS
        This will match the definition for a java 'Generic' class or interface
        Code:
        Exact Field Declaration Expression:
        public static final Pattern GENERIC_PARAMS = Pattern.compile("^.+?<([\\s\\w\\<>,\\?]+)>$");
        
      • PACKAGE_NAME

        🡅  🡇    
        public static final java.util.regex.Pattern PACKAGE_NAME
        This shall match a Java Package String
        Code:
        Exact Field Declaration Expression:
        public static final Pattern PACKAGE_NAME = Pattern.compile("([A-Za-z_]\\w*\\.)+");
        
      • REG_EX_ESCAPE_CHARS

        🡅  🡇    
        public static final java.lang.String REG_EX_ESCAPE_CHARS
        This is the list of characters that need to be escaped for a regular expression
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
        public static final String REG_EX_ESCAPE_CHARS = "\\/()[]{}$^+*?-.";
        
      • ALPHA_NUMERIC

        🡅  🡇    
        public static final java.util.regex.Pattern ALPHA_NUMERIC
        Alpha-Numeric RegEx
        Code:
        Exact Field Declaration Expression:
        public static final Pattern ALPHA_NUMERIC = Pattern.compile("^[\\d\\w]*$");
        
      • alphaNumPred

        🡅  🡇    
        public static final java.util.function.Predicate<java.lang.String> alphaNumPred
        Alpha-Numeric String Predicate.
        See Also:
        ALPHA_NUMERIC
        Code:
        Exact Field Declaration Expression:
        public static final Predicate<String> alphaNumPred = ALPHA_NUMERIC.asPredicate();
        
      • EMPTY_STR_ARRAY

        🡅  🡇    
        public static final java.lang.String[] EMPTY_STR_ARRAY
        An empty String array.
        Code:
        Exact Field Declaration Expression:
        public static final String[] EMPTY_STR_ARRAY = {};
        
      • JS_ESCAPE_CHARS

        🡅  🡇    
        protected static final char[] JS_ESCAPE_CHARS
        When converting a String for a Java-Script String, these are the characters that must be escaped.
        Code:
        Exact Field Declaration Expression:
        protected static final char[] JS_ESCAPE_CHARS = { '\\', '/', '\n', '\"' };
        
      • REGEX_ESCAPE_CHARS

        🡅  🡇    
        protected static final char[] REGEX_ESCAPE_CHARS
        These are 'control' characters (Reg Ex Code), so they must be escaped if the are to be treated as their ASCII-equivalent values.
        Code:
        Exact Field Declaration Expression:
        protected static final char[] REGEX_ESCAPE_CHARS =
            { '\\', '/', '(', ')', '[', ']', '{', '}', '$', '^', '+', '*', '?', '-', '.' };
        
      • FLOATING_POINT_REGEX

        🡅  🡇    
        public static final java.util.regex.Pattern FLOATING_POINT_REGEX
        A Predicate which uses a regular-expression for checking whether a String is a valid & parseable double, which is guaranteed not to throw a NumberFormatException when using the parser Double.parseDouble.

        The Following Description is Directly Copied From: java.lang.Double.valueOf(String), JDK 1.8

        Leading and trailing whitespace characters in s are ignored. Whitespace is removed as if by the String.trim() method; that is, both ASCII space and control characters are removed. The rest of s should constitute a FloatValue as described by the lexical syntax rules:

        FloatValue:
        Signopt NaN
        Signopt Infinity
        Signopt FloatingPointLiteral
        Signopt HexFloatingPointLiteral
        SignedInteger
        HexFloatingPointLiteral:
        HexSignificand BinaryExponent FloatTypeSuffixopt
        HexSignificand:
        HexNumeral
        HexNumeral .
        0x HexDigitsopt . HexDigits
        0X HexDigitsopt . HexDigits
        BinaryExponent:
        BinaryExponentIndicator SignedInteger
        BinaryExponentIndicator:
        p
        P
        where Sign, FloatingPointLiteral, HexNumeral, HexDigits, SignedInteger and FloatTypeSuffix are as defined in the lexical structure sections of The Java™ Language Specification, except that underscores are not accepted between digits. If s does not have the form of a FloatValue, then a NumberFormatException is thrown. Otherwise, s is regarded as representing an exact decimal value in the usual "computerized scientific notation" or as an exact hexadecimal value; this exact numerical value is then conceptually converted to an "infinitely precise" binary value that is then rounded to type double by the usual round-to-nearest rule of IEEE 754 floating-point arithmetic, which includes preserving the sign of a zero value.

        Note that the round-to-nearest rule also implies overflow and underflow behaviour; if the exact value of s is large enough in magnitude (greater than or equal to (Double.MAX_VALUE + Math.ulp(double) ulp(MAX_VALUE)/2), rounding to double will result in an infinity and if the exact value of s is small enough in magnitude (less than or equal to Double.MIN_VALUE/2), rounding to float will result in a zero.

        Finally, after rounding a Double object representing this double value is returned.

        To interpret localized string representations of a floating-point value, use subclasses of java.text.NumberFormat

        Note that trailing format specifiers, specifiers that determine the type of a floating-point literal (1.0f is a float value; 1.0d is a double value), do not influence the results of this method. In other words, the numerical value of the input string is converted directly to the target floating-point type. The two-step sequence of conversions, string to float followed by float to double, is not equivalent to converting a string directly to double. For example, the float literal 0.1f is equal to the double value 0.10000000149011612; the float literal 0.1f represents a different numerical value than the double literal 0.1. (The numerical value 0.1 cannot be exactly represented in a binary floating-point number.)

        To avoid calling this method on an invalid string and having a NumberFormatException be thrown, the regular expression below can be used to screen the input string

        See Also:
        floatingPointPred, isDouble(String)
        Code:
        Exact Field Declaration Expression:
        public static final Pattern FLOATING_POINT_REGEX = Pattern.compile(
                "[\\x00-\\x20]*"+  // Optional leading "whitespace"
                "[+-]?(" + // Optional sign character
                "NaN|" +           // "NaN" string
                "Infinity|" +      // "Infinity" string
          
                // A decimal floating-point string representing a finite positive
                // number without a leading sign has at most five basic pieces:
                // Digits . Digits ExponentPart FloatTypeSuffix
                //
                // Since this method allows integer-only strings as input
                // in addition to strings of floating-point literals, the
                // two sub-patterns below are simplifications of the grammar
                // productions from section 3.10.2 of
                // The Java Language Specification.
          
                // Digits ._opt Digits_opt ExponentPart_opt FloatTypeSuffix_opt
                "((("+Digits+"(\\.)?("+Digits+"?)("+Exp+")?)|"+
          
                // . Digits ExponentPart_opt FloatTypeSuffix_opt
                "(\\.("+Digits+")("+Exp+")?)|"+
          
                // Hexadecimal strings
                "((" +
                // 0[xX] HexDigits ._opt BinaryExponent FloatTypeSuffix_opt
                "(0[xX]" + HexDigits + "(\\.)?)|" +
          
                // 0[xX] HexDigits_opt . HexDigits BinaryExponent FloatTypeSuffix_opt
                "(0[xX]" + HexDigits + "?(\\.)" + HexDigits + ")" +
          
                ")[pP][+-]?" + Digits + "))" +
                "[fFdD]?))" +
                "[\\x00-\\x20]*"
                // Optional trailing "whitespace";
            );
        
      • floatingPointPred

        🡅  🡇    
        public static final java.util.function.Predicate<java.lang.String> floatingPointPred
        This is the floating-point regular-expression, simply converted to a predicate.
        See Also:
        FLOATING_POINT_REGEX, isDouble(String)
        Code:
        Exact Field Declaration Expression:
        public static final Predicate<String> floatingPointPred = FLOATING_POINT_REGEX.asPredicate();
        
    • Method Detail

      • commas

        🡅  🡇    
        public static java.lang.String commas​(long l)
        Makes a long number like 123456789 into a number-string such as: "123,456,789". Java's package java.text.* is easy to use, and versatile, but the commands are not always so easy to remember.
        Parameters:
        l - Any long integer. Comma's will be inserted for every third power of ten
        Returns:
        After calling java's java.text.DecimalFormat class, a String representing this parameter will be returned.
        Code:
        Exact Method Body:
         return formatter.format(l);
        
      • trimRight

        🡅  🡇    
        public static java.lang.String trimRight​(java.lang.String s)
        Trims any white-space Characters from the end of a String.
        Input String:Output String:
        "A Quick Brown Fox\n \t""A Quick Brown Fox"
        "\tA Lazy Dog.""\tA Lazy Dog."
        " " (only white-space)""
        "" (empty-string)""
        nullthrows NullPointerException
        Parameters:
        s - Any Java String
        Returns:
        A copy of the same String - but all characters that matched Java method java.lang.Character.isWhitespace(char) and were at the end of the String will not be included in the returned String.

        If the zero-length String is passed to parameter 's', it shall be returned immediately.

        If the resultant-String has zero-length, it is returned, without exception.
        Code:
        Exact Method Body:
         if (s.length() == 0) return s;
        
         int pos = s.length();
        
         while ((pos > 0) && Character.isWhitespace(s.charAt(--pos)));
        
         if (pos == 0) if (Character.isWhitespace(s.charAt(0))) return "";
        
         return s.substring(0, pos + 1);
        
      • trimLeft

        🡅  🡇    
        public static java.lang.String trimLeft​(java.lang.String s)
        Trims any white-space Characters from the beginning of a String.
        Input String:Output String:
        "\t A Quick Brown Fox""A Quick Brown Fox"
        "A Lazy Dog. \n\r\t""A Lazy Dog. \n\r\t"
        " " (only white-space)""
        "" (empty-string)""
        nullthrows NullPointerException
        Parameters:
        s - Any Java String
        Returns:
        A copy of the same String - but all characters that matched Java method java.lang.Character.isWhitespace(char) and were at the start of the String will not be included in the returned String.

        If the zero-length String is passed to parameter 's', it shall be returned immediately.

        If the resultant-String has zero-length, it is returned, without exception.
        Code:
        Exact Method Body:
         int pos = 0;
         int len = s.length();
        
         if (len == 0) return s;
        
         while ((pos < len) && Character.isWhitespace(s.charAt(pos++)));
        
         if (pos == len) if (Character.isWhitespace(s.charAt(len-1))) return "";
        
         return s.substring(pos - 1);
        
      • leftSpacePad

        🡅  🡇    
        public static java.lang.String leftSpacePad​(java.lang.String s,
                                                    int totalStringLength)
        Primarily for convenience in remembering earlier C-style printf(...) formatting commands.

        This method will "left pad" an input String with spaces, if s.length() < totalStrLength. If input-parameter 's' is equal-to or longer-than the value in 'totalStringLength', then the original String shall be returned.
        Input ParametersReturned String
        "Quick Brown Fox"
        20
        "     Quick Brown Fox"
        "Hello World"
        15
        "    Hello World"
        "Write Once, Run Anywhere"
        10
        "Write Once, Run Anywhere"
        nullNullPointerException
        Parameters:
        s - This may be any java.lang.String
        totalStringLength - If s.length() is smaller than 'totalStringLength', then as many space characters (' ') as are needed to ensure that the returned 'String' has length equal to 'totalStringLength' will be prepended to the input String parameter 's'.

        If s.length() is greater than 'totalStringLength', then the original input shall be returned.
        Throws:
        java.lang.IllegalArgumentException - If totalStringLength is zero or negative.
        See Also:
        rightSpacePad(String, int)
        Code:
        Exact Method Body:
         if (totalStringLength <= 0) throw new IllegalArgumentException(
             "totalString length was '" + totalStringLength + ", " +
             "however it is expected to be a positive integer."
         );
        
         return (s.length() >= totalStringLength) 
             ? s 
             : String.format("%1$" + totalStringLength + "s", s);
        
      • rightSpacePad

        🡅  🡇    
        public static java.lang.String rightSpacePad​(java.lang.String s,
                                                     int totalStringLength)
        Primarily for convenience in remembering earlier C-style printf(...) formatting commands.

        This method will "right pad" an input String with spaces, if s.length() < totalStrLength. If input-parameter 's' is equal-to or longer-than the value in 'totalStringLength', then the original String shall be returned.
        Input ParametersReturned String
        "Quick Brown Fox"
        20
        "Quick Brown Fox     "
        "Hello World"
        15
        "Hello World    "
        "Write Once, Run Anywhere"
        10
        "Write Once, Run Anywhere"
        nullNullPointerException
        Parameters:
        s - This may be any java.lang.String
        totalStringLength - If s.length() is smaller than 'totalStringLength', then as many space characters (' ') as are needed to ensure that the returned 'String' has length equal to 'totalStringLength' will be postpended to the input String parameter 's'.

        If s.length() is greater than 'totalStringLength', then the original input shall be returned.
        Throws:
        java.lang.IllegalArgumentException - If totalStringLength is zero or negative.
        See Also:
        leftSpacePad(String, int)
        Code:
        Exact Method Body:
         if (totalStringLength <= 0) throw new IllegalArgumentException(
             "totalString length was '" + totalStringLength + "', " +
             "however it is expected to be a positive integer."
         );
        
         return (s.length() >= totalStringLength) 
             ? s 
             : String.format("%1$-" + totalStringLength + "s", s);
        
      • setChar

        🡅  🡇    
        public static java.lang.String setChar​(java.lang.String str,
                                               int i,
                                               char c)
        This sets a character in a String to a new value, and returns a result.
        Parameters:
        str - Any java String
        i - An index into the underlying character array of that String.
        c - A new character to be placed at the i'th position of this String.
        Returns:
        a new java String, with the appropriate index into the String substituted using character parameter 'c'.
        Code:
        Exact Method Body:
         if ((i + 1) < str.length()) return str.substring(0, i) + c + str.substring(i + 1);
         else                        return str.substring(0, i) + c;
        
      • delChar

        🡅  🡇    
        public static java.lang.String delChar​(java.lang.String str,
                                               int i)
        This removes a character from a String, and returns a new String as a result.
        Parameters:
        str - Any Java-String.
        i - This is the index into the underlying java char-array whose character will be removed from the return String.
        Returns:
        Since Java String's are all immutable, this String that is returned is completely new, with the character that was originally at index 'i' removed.
        Code:
        Exact Method Body:
         if ((i + 1) < str.length())
             return str.substring(0, i) + str.substring(i + 1);
         else
             return str.substring(0, i);
        
      • removeDuplicateSpaces

        🡅  🡇    
        public static java.lang.String removeDuplicateSpaces​(java.lang.String s)
        Returns the same String is input, but trims all spaces down to a single space. Each and every lone / independent or contiguous white-space character is reduced to a single space-character.
        Input StringOutput String
        "This   has   extra   spaces\n"
        "This has extra spaces "
        "This does not" "This does not"
        "\tThis\nhas\ttabs\nand\tnewlines\n" " This has tabs and newlines "
        Parameters:
        s - Any Java String
        Returns:
        A String where all white-space is compacted to a single space. This is generally how HTML works, when it is displayed in a browser.
        Code:
        Exact Method Body:
         return StringParse.WHITE_SPACE_REGEX.matcher(s).replaceAll(" ");
        
      • removeWhiteSpace

        🡅  🡇    
        public static java.lang.String removeWhiteSpace​(java.lang.String s)
        This string-modify method simply removes any and all white-space matches found within a java-String.
        Input StringOutput String
        "This   Has   Extra   Spaces\n"
        "ThisHasExtraSpaces"
        "This Does Not" "ThisDoesNot"
        "\tThis\nHas\tTabs\nAnd\tNewlines\n" "ThisHasTabsAndNewlines"
        Parameters:
        s - Any String, but if it has any white-space (space that matches regular-expression: \w+) then those character-blocks will be removed
        Returns:
        A new String without any \w (RegEx for 'whitespace')
        See Also:
        WHITE_SPACE_REGEX
        Code:
        Exact Method Body:
         return WHITE_SPACE_REGEX.matcher(s).replaceAll("");
        
      • nChars

        🡅  🡇    
        public static java.lang.String nChars​(char c,
                                              int n)
        Generates a String that contains n copies of character c.
        Returns:
        n copies of c, as a String.
        See Also:
        caretBeneath(String, int)
        Code:
        Exact Method Body:
         char[] cArr = new char[n];
         Arrays.fill(cArr, c);
         return new String(cArr);
        
      • nStrings

        🡅  🡇    
        public static java.lang.String nStrings​(java.lang.String s,
                                                int n)
        Generates a String that contains n copies of s.
        Returns:
        n copies of s as a String.
        Throws:
        NException - if the value provided to parameter 'n' is negative.
        Code:
        Exact Method Body:
         if (n < 0) throw new NException("A negative value was passed to 'n' [" + n + ']');
        
         StringBuilder sb = new StringBuilder();
        
         for (int i=0; i < n; i++) sb.append(s);
        
         return sb.toString();
        
      • lineOrLines

        🡅  🡇    
        public static java.lang.String lineOrLines​(java.lang.String s,
                                                   int pos,
                                                   int len,
                                                   java.lang.String unixColorCode)
        This will return the complete text-lines of character data for the line identified by token-substring position parameters pos and len. This method will search, in the left-direction (decreasing String index) for the first new-line character identified. It will also search, starting at position pos + len, for the first new-line character in the right-direction (increasing String index).

        If the token-substring identified by s.substring(pos, len) itself contains any new-line characters, these will neither affect the prepended, nor the post-pended search String. To be precise, any newline characters between 'pos' and 'len' will be irrelevant to the left-wards and right-wards newlines searches for new-line characters.
        Parameters:
        s - This may be any valid Java String. It ought to be some variant of a text-file. It will be searched for the nearest '\n' character - in both directions, left and right - from parameter int 'pos' and parameter int 'len'
        pos - This is a position in the input-parameter String 's'. The nearest '\n' (new-line) character, to the left of this position, will be found and identified. If the char at s.charAt(pos) is, itself, a '\n' (newline) character, then no left-direction search will be performed. The left-most position of the returned substring would then be pos + 1.
        len - The search for the 'right-most' '\n' (newline-character) will begin at position 'len'. If the character at s.charAt(pos + len) is, itself, a new-line character, then no right-direction search will be performed. The right-most position of the returned substring would be pos + len - 1.
        unixColorCode - If this String is null, it will be ignored. If this String is non-null, it will be inserted before the "Matching String" indicated by the index-boundaries pos TO pos + len.

        NOTE: No Validity Check shall be performed on this String, and the user is not obligated to provide a Shell.C valid UNIX Color-Code String. Also, a closing C.RESET is inserted after the terminus of the match.
        Returns:
        The String demarcated by the first new-line character PLUS 1 BEFORE index 'pos', and the first new-line character MINUS 1 AFTER index pos + len.

        NOTE: The above does mean, indeed, that the starting and ending new-lines WILL NOT be included in the returned String.

        ALSO: Also, if there are no new-line characters before position 'pos', then every character beginning at position zero will be included in the returned String result. Also, if there are no new-line characters after position pos + len then every character after position pos + len will be appended to the returned String result.
        Throws:
        java.lang.StringIndexOutOfBoundsException - If either 'pos', or 'pos + len' are not within the bounds of the input String 's'
        java.lang.IllegalArgumentException - If the value passed to parameter 'len' is zero or negative.
        Code:
        Exact Method Body:
         if ((pos >= s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException(
             "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end " +
             "of String 's', which has length [" + s.length() + "]"
         );
        
         if (len <= 0) throw new IllegalArgumentException
             ("The value passed to parameter 'len' [" + len + "], may not be negative.");
        
         if ((pos + len) > s.length()) throw new StringIndexOutOfBoundsException(
             "The total of parameter 'pos' [" + pos + "], and parameter 'len' [" + len + "], is: " +
             "[" + (pos + len) + "].  Unfortunately, String parameter 's' only has length " +
             "[" + s.length() + "]"
         );
        
         int linesStart, linesEnd, temp;
        
         if (pos == 0)                                           linesStart  = 0;
         else if (s.charAt(pos) == '\n')                         linesStart  = pos + 1; 
         else if ((temp = StrIndexOf.left(s, pos, '\n')) != -1)  linesStart  = temp + 1;
         else                                                    linesStart  = 0;
        
         if ((pos + len) == s.length())                          linesEnd    = s.length();
         else if (s.charAt(pos + len) == '\n')                   linesEnd    = pos + len;
         else if ((temp = s.indexOf('\n', pos + len)) != -1)     linesEnd    = temp;
         else                                                    linesEnd    = s.length();
        
         /*
         // VERY USEFUL FOR DEBUGGING.  DO NOT DELETE...
         // NOTE: This method is the one that GREP uses.
         System.out.println("s.charAt(pos)\t\t= "    + "[" + s.charAt(pos) + "]");
         System.out.println("s.charAt(pos+len)\t= "  + "[" + s.charAt(pos+len) + "]");
         System.out.println("s.length()\t\t= "       + s.length());
         System.out.println("pos\t\t\t= "            + pos);
         System.out.println("pos + len\t\t= "        + (pos + len));
         System.out.println("linesStart\t\t= "       + linesStart);
         System.out.println("linesEnd\t\t= "         + linesEnd);
         */
        
         return  (unixColorCode != null)
             ?   s.substring(linesStart, pos) + 
                 unixColorCode + s.substring(pos, pos + len) + C.RESET + 
                 s.substring(pos + len, linesEnd)
             :   s.substring(linesStart, linesEnd);
                 /*
                 OOPS.... For Posterity, this shall remain, here, but commented
                 s.substring(linesStart, pos) + 
                 s.substring(pos, pos + len) + 
                 s.substring(pos + len, linesEnd);
                 */
        
      • line

        🡅  🡇    
        public static java.lang.String line​(java.lang.String s,
                                            int pos)
        This will return the complete text-line of character data from 'inside' the input-parameter String s. The meaning of 'complete text-line', in this method, is that any and all character data between the first '\n' (new-line character) when scanning towards the right (increasing String-index) and the first '\n' character when scanning towards the left (decreasing index) constitutes 'a line' (of text-data).

        This scan shall for the left-most and right-most new-line shall begin at String-index parameter pos. If either the left-direction or right-direction scan does not find any new-line characters, then start and end indices of the returned line of text shall be demarcated by input-String index '0' and index String.length(), respectively
        Parameters:
        s - This may be any valid Java String. It ought to be some variant of a text-file. It will be searched for the nearest '\n' character - in both directions, left and right - from parameter int 'pos'.
        pos - This is a position in the input-parameter String 's'. The nearest new-line character both to the left of this position, and to the right, will be found and identified. If the character at s.charAt(pos) is itself a newline '\n' character, then an exception shall throw.
        Returns:
        The String identified by the first new-line character PLUS 1 BEFORE index 'pos', and the first new-line character MINUS 1 AFTER index 'pos + len'.

        NOTE: The above means, that the starting and ending new-lines, themselves, will not be included in the String that is returned.

        ALSO: Also, if there are no new-line characters before position 'pos', then every character beginning at position zero will be included in the returned String result. Also, if there are no new-line characters after position 'pos + len' then every character after position 'pos + len' will be appended to the returned String result.
        Throws:
        java.lang.StringIndexOutOfBoundsException - If is not within the bounds of the input String 's'
        java.lang.IllegalArgumentException - If the character in String 's' at position 'pos' is a newline '\n', itself.
        Code:
        Exact Method Body:
         if ((pos > s.length()) || (pos < 0)) throw new StringIndexOutOfBoundsException(
             "The integer passed to parameter 'pos' [" + pos + "], is past the bounds of the end of " +
             "String 's', which has length [" + s.length() + "]"
         );
        
         if (s.charAt(pos) == '\n') throw  new IllegalArgumentException(
             "The position-index for string-parameter 's' contains, itself, a new line character " +
             "'\\n.'  This is not allowed here."
         );
        
         int lineStart   = StrIndexOf.left(s, pos, '\n');
         int lineEnd     = s.indexOf('\n', pos);
        
         if (lineStart == -1)    lineStart   = 0;
         if (lineEnd == -1)      lineEnd     = s.length();
        
         return  s.substring(lineStart + 1, lineEnd);
        
      • numLines

        🡅  🡇    
        public static int numLines​(java.lang.String text)
        Counts the number of lines of text inside of a Java String.
        Parameters:
        text - This may be any text, as a String.
        Returns:
        Returns the number of lines of text. The integer returned shall be precisely equal to the number of '\n' characters plus one!
        Code:
        Exact Method Body:
         if (text.length() == 0) return 0;
        
         int pos     = -1;
         int count   = 0;
        
         do
         {
             pos = text.indexOf('\n', pos + 1);
             count++;
         }
         while (pos != -1);
        
         return count;
        
      • hasWhiteSpace

        🡅  🡇    
        public static boolean hasWhiteSpace​(java.lang.String s)
        This method checks whether or not a java-String has white-space.
        Parameters:
        s - Any Java-String. If this String has any white-space, this method will return TRUE
        Returns:
        TRUE If there is any white-space in this method, and FALSE otherwise.
        See Also:
        WHITE_SPACE_REGEX
        Code:
        Exact Method Body:
         return WHITE_SPACE_REGEX.matcher(s).find();
        
      • countCharacters

        🡅  🡇    
        public static int countCharacters​(java.lang.String s,
                                          char c)
        Counts the number of instances of character input char c contained by the input String s
        Parameters:
        s - Any String containing any combination of ASCII/UniCode characters
        c - Any ASCII/UniCode character.
        Returns:
        The number of times char c occurs in String s
        Code:
        Exact Method Body:
         int count = 0;
         int pos   = 0;
         while ((pos = s.indexOf(c, pos + 1)) != -1) count++;
         return count;
        
      • ifQuotesStripQuotes

        🡅  🡇    
        public static java.lang.String ifQuotesStripQuotes​(java.lang.String s)
        If the String passed to this method contains a single-quote on both sides of the String, or if it contains a double-quote on both sides of this String, then this method shall return a new String that is shorter in length by 2, and leaves off the first and last characters of the input parameter String.

        HOPEFULLY, The name of this method explains clearly what this method does
        Parameters:
        s - This may be any java String. Only String's whose first and last characters are not only quotation marks (single or double), but also they are the same, identical, quotation marks on each side.
        Returns:
        A new String that whose first and last quotation marks are gone - if they were there when this method began.
        Code:
        Exact Method Body:
         if (s == null)      return null;
         if (s.length() < 2) return s;
        
         int lenM1 = s.length() - 1; // Position of the last character in the String
        
         if (    ((s.charAt(0) == '\"')  && (s.charAt(lenM1) == '\"'))       // String has Double-Quotation-Marks
                                         ||                                  //            ** or ***
                 ((s.charAt(0) == '\'')  && (s.charAt(lenM1) == '\''))  )    // String has Single-Quotation-Marks
             return s.substring(1, lenM1);
         else  
             return s;
        
      • monthStr

        🡅  🡇    
        public static java.lang.String monthStr​(int month)
        Converts an integer into a Month. I could just use the class java.util.Calendar, but it is so complicated, that using an internal array is easier.

        String months[] = { month names };
        Parameters:
        month - The month, as a number from '1' to '12'.
        Returns:
        A month as a String like: "January" or "August"
        Code:
        Exact Method Body:
         return months[month-1];
        
      • dateStr

        🡅  🡇    
        public static java.lang.String dateStr()
        Generates a "Date String" using the character separator '.'
        Returns:
        A String in the form: YYYY.MM.DD
        Code:
        Exact Method Body:
         return dateStr('.', false);
        
      • dateStr

        🡅  🡇    
        public static java.lang.String dateStr​(char separator)
        Generates a "Date String" using the separator parameter as the separator between numbers
        Parameters:
        separator - Any ASCII or UniCode character.
        Returns:
        A String of the form: YYYYcMMcDD where 'c' is the passed 'separator' parameter.
        Code:
        Exact Method Body:
         return dateStr(separator, false);
        
      • dateStrGOVCN

        🡅  🡇    
        public static java.lang.String dateStrGOVCN()
        Generates a "Date String" that is consistent with the directory-name file-storage locations used to store articles from http://Gov.CN.
        Returns:
        The String's used for the Chinese Government Web-Portal Translation Pages
        Code:
        Exact Method Body:
         return dateStr('/', false).replaceFirst("/", "-");
        
      • dateStr

        🡅  🡇    
        public static java.lang.String dateStr​(char separator,
                                               boolean includeMonthName)
        This class is primary included because although Java has a pretty reasonable "general purpose" calendar class/interface, but a consistent / same String since is needed because the primary use here is for building the names of files.
        Parameters:
        separator - Any ASCII or Uni-Code character.
        includeMonthName - When TRUE, the English-Name of the month ('January' ... 'December') will be appended to the month number in the returned String.
        Returns:
        The year, month, and day as a String.
        Code:
        Exact Method Body:
         Calendar    c   = internalCalendar;
         String      m   = zeroPad10e2(c.get(Calendar.MONTH) + 1); // January is month zero!
         String      d   = zeroPad10e2(c.get(Calendar.DAY_OF_MONTH));
        
         if (includeMonthName) m += " - " + c.getDisplayName(Calendar.MONTH, 2, Locale.US);
        
         if (separator != 0) return c.get(Calendar.YEAR) + "" + separator + m + separator + d;
         else                return c.get(Calendar.YEAR) + "" + m + d;
        
      • ymDateStr

        🡅  🡇    
        public static java.lang.String ymDateStr()
        Returns a String that has the year and the month (but not the day, or other time components).
        Returns:
        Returns the current year and month as a String.
        Code:
        Exact Method Body:
         return ymDateStr('.', false);
        
      • ymDateStr

        🡅  🡇    
        public static java.lang.String ymDateStr​(char separator)
        Returns a String that has the year and the month (but not the day, or other time components).
        Parameters:
        separator - The single-character separator used between year, month and day.
        Returns:
        The current year and month as a String.
        Code:
        Exact Method Body:
         return ymDateStr(separator, false);
        
      • ymDateStr

        🡅  🡇    
        public static java.lang.String ymDateStr​(char separator,
                                                 boolean includeMonthName)
        Returns a String that has the year and the month (but not the day, or other time components).
        Parameters:
        separator - The single-character separator used between year, month and day.
        includeMonthName - When this is true, the name of the month, in English, is included with the return String.
        Returns:
        YYYYseparatorMM(? include-month-name)
        Code:
        Exact Method Body:
         Calendar    c   = internalCalendar;
         String      m   = zeroPad10e2(c.get(Calendar.MONTH) + 1); // January is month zero!
        
         if (includeMonthName) m += " - " + c.getDisplayName(Calendar.MONTH, 2, Locale.US);
        
         if (separator != 0) return c.get(Calendar.YEAR) + "" + separator + m;
         else                return c.get(Calendar.YEAR) + "" + m;
        
      • timeStr

        🡅  🡇    
        public static java.lang.String timeStr()
        Returns the current time as a String.
        Returns:
        military time - with AM|PM (redundant) added too. Includes only Hour and Minute - separated by a colon character ':'
        See Also:
        timeStr(char)
        Code:
        Exact Method Body:
         return timeStr(':');
        
      • timeStr

        🡅  🡇    
        public static java.lang.String timeStr​(char separator)
        Returns the current time as a String.
        Parameters:
        separator - The character used to separate the minute & hour fields
        Returns:
        military time - with AM|PM added redundantly, and a separator of your choosing.
        Code:
        Exact Method Body:
         Calendar    c   = internalCalendar;
         int         ht  = c.get(Calendar.HOUR) + ((c.get(Calendar.AM_PM) == Calendar.AM) ? 0 : 12);
         String      h   = zeroPad10e2((ht == 0) ? 12 : ht);  // 12:00 is represented as "0"... changes this...
         String      m   = zeroPad10e2(c.get(Calendar.MINUTE));
         String      p   = (c.get(Calendar.AM_PM) == Calendar.AM) ? "AM" : "PM";
        
         if (separator != 0) return h + separator + m + separator + p;
         else                return h + m + p;
        
      • timeStrComplete

        🡅  🡇    
        public static java.lang.String timeStrComplete()
        Returns the current time as a String. This method uses all time components available.
        Returns:
        military time - with AM|PM added redundantly.
        Code:
        Exact Method Body:
         Calendar    c   = internalCalendar;
         int         ht  = c.get(Calendar.HOUR) + ((c.get(Calendar.AM_PM) == Calendar.AM) ? 0 : 12);
         String      h   = zeroPad10e2((ht == 0) ? 12 : ht);  // 12:00 is represented as "0"
         String      m   = zeroPad10e2(c.get(Calendar.MINUTE));
         String      s   = zeroPad10e2(c.get(Calendar.SECOND));
         String      ms  = zeroPad(c.get(Calendar.MILLISECOND));
         String      p   = (c.get(Calendar.AM_PM) == Calendar.AM) ? "AM" : "PM";
        
         return h + '-' + m + '-' + p + '-' + s + '-' + ms + "ms";
        
      • ordinalIndicator

        🡅  🡇    
        public static java.lang.String ordinalIndicator​(int i)
        The words "ordinal indicator" are referring to the little character String that is often used in English to make a number seem more a part of an english sentence.
        Parameters:
        i - Any positive integer (greater than 0)
        Returns:
        This will return the following strings:
        Input: RETURNS:
        i = 1 "st"  (as in "1st","first")
        i = 2 "nd"  (as in "2nd", "second")
        i = 4 "th"  (as in "4th")
        i = 23 "rd"  (as in "23rd")
        Throws:
        java.lang.IllegalArgumentException - If i is negative, or zero
        Code:
        Exact Method Body:
         if (i < 1)
             throw new IllegalArgumentException("i: " + i + "\tshould be a natural number > 0.");
        
         // Returns the last 2 digits of the number, or the number itself if it is less than 100.
         // Any number greater than 100 - will not have the "text-ending" (1st, 2nd, 3rd..) affected
         // by the digits after the first two digits.  Just analyze the two least-significant digits
         i = i % 100;
        
         // All numbers between "4th" and "19th" end with "th"
         if ((i > 3) && (i < 20))    return "th";
        
         // set i to be the least-significant digit of the number - if that number was 1, 2, or 3
         i = i % 10;
        
         // Obvious: English Rules.
         if (i == 1)                 return "st";
         if (i == 2)                 return "nd";
         if (i == 3)                 return "rd";
        
         // Compiler is complaining.  This statement should never be executed.
         return "th";
        
      • zeroPad

        🡅  🡇    
        public static java.lang.String zeroPad​(int n)
        This just zero-pads integers with "prepended" zero's. java.text has all kinds of extremely intricate zero-padding and text-formatting classes. However, here, these are generally used for debug, line-number, or count information that is printed to the UNIX terminal. When this is the case, a simple and easily remembered 'one line method' is a lot more useful than all of the highly-scalable versions of the text-formatting classes in java.text.
        Parameters:
        n - Any Integer. If 'n' is negative or greater than 1,000 - then null is returned.
        Returns:
        A zero-padded String - to precisely three orders of 10, as in the example table below:
        Input RETURNS:
        n = 9 "009"
        n = 99 "099"
        n = 999 "999"
        n = 9999 null
        n = -10 null
        See Also:
        zeroPad10e2(int), zeroPad10e4(int)
        Code:
        Exact Method Body:
         if (n < 0)      return null;
         if (n < 10)     return "00" + n;
         if (n < 100)    return "0" + n;
         if (n < 1000)   return "" + n;
         return null;
        
      • zeroPad10e2

        🡅  🡇    
        public static java.lang.String zeroPad10e2​(int n)
        Pads an integer such that it contains enough leading zero's to ensure a String-length of two.
        Parameters:
        n - Must be an integer between 0 and 99, or else null will be returned
        Returns:
        A zero-padded String of the integer, to precisely two orders of 10
        . Null is returned if the number cannot fit within two spaces. Example table follows:
        Input RETURNS:
        n = 9 "09"
        n = 99 "99"
        n = 999 null
        n = -10 null
        See Also:
        zeroPad(int)
        Code:
        Exact Method Body:
         if (n < 0)      return null;
         if (n < 10)     return "0" + n;
         if (n < 100)    return "" + n;
         return null;
        
      • zeroPad10e4

        🡅  🡇    
        public static java.lang.String zeroPad10e4​(int n)
        Pads an integer such that it contains enough leading zero's to ensure a String-length of four.
        Parameters:
        n - Must be an integer between 0 and 9999, or else null will be returned
        Returns:
        A zero-padded String of the integer, to precisely four orders of 10. Null is returned if the number cannot fit within four spaces. Example table follows:
        Input RETURNS:
        n = 9 "0009"
        n = 99 "0099"
        n = 999 "0999"
        n = 9999 "9999"
        n = 99999 null
        n = -10 null
        See Also:
        zeroPad(int)
        Code:
        Exact Method Body:
         if (n < 0)      return null;
         if (n < 10)     return "000" + n;
         if (n < 100)    return "00" + n;
         if (n < 1000)   return "0" + n;
         if (n < 10000)  return "" + n;
         return null;
        
      • zeroPad

        🡅  🡇    
        public static java.lang.String zeroPad​(int n,
                                               int powerOf10)
        Pad's an integer with leading zeroes into a String. The number of zeroes padded is equal to parameter 'powerOf10'. If int 'powerOf10' were equal to zero, then any integer passed to this function would return a String that was precisely three characters long. If the value of parameter int 'n' were larger than 1,000 or negative, then null would be returned.
        Parameters:
        n - Must be an integer between '0' and '9999' where the number of '9' digits is equal to the value of parameter int 'powerOf10'
        powerOf10 - This must be a positive integer greater than '1'. It may not be larger '11'. The largest value that any integer in Java may attain is '2,147,483, 647'
        Returns:
        A zero padded String. If a negative number is passed to parameter 'n', then 'null' shall be returned. Null shall also be returned if the "Power of 10 Exponent of parameter n" is greater than the integer-value of parameter 'powerOf10'

        FOR INSTANCE: a call to: zeroPad(54321, 4); would return null since the value of parameter 'n' has five-decimal-places, but 'powerOf10' is only 4!
        Throws:
        java.lang.IllegalArgumentException - if the value parameter 'powerOf10' is less than 2, or greater than 11.
        Code:
        Exact Method Body:
         if (n < 0) return null;                 // Negative Values of 'n' not allowed
        
         char[]  cArr    = new char[powerOf10];  // The String's length will be equal to 'powerOf10'
         String  s       = "" + n;               //       (or else 'null' would be returned)
         int     i       = powerOf10 - 1;        // Internal Loop variable
         int     j       = s.length() - 1;       // Internal Loop variable
        
         Arrays.fill(cArr, '0');                 // Initially, fill the output char-array with all
                                                 // zeros
        
         while ((i >= 0) && (j >= 0))            // Now start filling that char array with the
             cArr[i--] = s.charAt(j--);          // actual number
        
         if (j >= 0) return null;                // if all of parameter 'n' was inserted into the
                                                 // output (number 'n' didn't fit) then powerOf10
                                                 // was insufficient, so return null.
        
         return new String(cArr);
        
      • grep_HREF_tag

        🡅  🡇    
        public static java.lang.String grep_HREF_tag​(java.lang.String s)
        If parameter String s contains any tag within-which there is a valid "HREF", this will return the contents of the HREF Attribute/InnerTag.
        Parameters:
        s - This is usually some variant of an HTML element/tag String. This method was the first one written for HTML in this scrape package, and is just kept here for legacy reasons. The class HTML.TagNode has a number of options for extracting the 'HREF' attribute from an HTML element.
        Returns:
        The attribute-value of an HREF=... attribute inside (usually an <A> 'Anchor') HTML tag. This will return 'null' if there is no HREF="..." attribute-value pair is found or identified.
        Throws:
        java.lang.IllegalArgumentException - If there is no end-quote found for the HREF="..." sub-string.
        Code:
        Exact Method Body:
         s = s.toLowerCase();
         String quote = "\"";
        
         int hrefPos = s.indexOf("href=\"");
        
         if (hrefPos == -1)
         {
             hrefPos = s.indexOf("href='");
             if (hrefPos == -1) return null;
             quote = "'";
         }
        
         // System.out.print("\t[hrefPos=" + hrefPos + "]");
                
         // the " + 6" is because the string HREF=" is 6 characters long
         String ret = s.substring(hrefPos + 6);
         int endQuotePos = ret.indexOf(quote);
                
         if (endQuotePos == -1) throw new IllegalArgumentException
             ("HREF has no End-Quote!\n\nFor String:\n" + s);
        
         // System.out.print("endQuotePos = " + endQuotePos + " " + ret.substring(0, endQuotePos));
        
         return ret.substring(0,endQuotePos);
        
      • grep_IMG_SRC_tag

        🡅  🡇    
        public static java.lang.String grep_IMG_SRC_tag​(java.lang.String s)
        If parameter String s contains an HTML "IMG" tag, this will return the contents of the "SRC=..." attribute tag-field.
        Parameters:
        s - This is usually some variant of an HTML element/tag String. This method was the first one written for HTML in this scrape package, and is just kept here for legacy reasons. The class HTML.TagNode has a number of options for extracting the 'SRC' attribute from an HTML element.
        Returns:
        The attribute-value of a SRC=... attribute inside (usually an <IMG> 'Image') HTML tag. 'null' is returned if:

        1. There is no HTML 'IMG' token found in the String
        2. There is no SRC='...' attribute-value pair found.
        Code:
        Exact Method Body:
         String stlc = s.toLowerCase();
         // System.out.println("1: " + stlc);
                
         int imgPos = stlc.indexOf("<img ");
        
         if (imgPos == -1) return null;
        
         stlc = stlc.substring(imgPos + 5);
         // System.out.println("2: " + stlc + "[imgPos=" + imgPos + "]");
        
         // first check for double-quotes
         String  quote   = "\"";
         int     srcPos  = stlc.indexOf("src=\"");
        
         if (srcPos == -1)
         {
             // if no double-quotes, try single quotes
             srcPos = stlc.indexOf("src='");
        
             if (srcPos == -1) return null;
        
             quote = "'";
         }
        
         stlc = stlc.substring(srcPos + 5);
        
         // System.out.println("3: " + stlc + "[srcPos=" + srcPos + "]");
                
         int endSrcPos = stlc.indexOf(quote);
        
         if (endSrcPos == -1) return null;
                
         int urlStart    = imgPos + srcPos + 10;
         int urlEnd      = urlStart + endSrcPos;
                
         // System.out.println
         //     ("4: [endSrcPos=" + endSrcPos + ", urlStart=" + urlStart + ", urlEnd=" + urlEnd);
        
         return s.substring(urlStart, urlEnd);
        
      • findLastFrontSlashPos

        🡅  🡇    
        public static int findLastFrontSlashPos​(java.lang.String urlOrDir)
        This function finds the position of the last "front-slash" character '/' in a java-String
        Parameters:
        urlOrDir - This is any java-String, but preferably one that is a URL, or directory.
        Returns:
        The String-index of the last 'front-slash' '/' position in a String, or -1 if there are not front-slashes.
        Code:
        Exact Method Body:
         return urlOrDir.lastIndexOf('/');
        
      • fromLastFrontSlashPos

        🡅  🡇    
        public static java.lang.String fromLastFrontSlashPos​
                    (java.lang.String urlOrDir)
        
        This returns the contents of a String, after the last front-slash found.

        NOTE: If not front-slash '/' character is found, then the original String is returned.
        Parameters:
        urlOrDir - This is any java-String, but preferably one that is a URL, or directory.
        Returns:
        the portion of the String after the final front-slash '/' character. If there are no front-slash characters found in this String, then the original String shall be returned.
        Code:
        Exact Method Body:
         int pos = urlOrDir.lastIndexOf('/');
         if (pos == -1) return urlOrDir;
         return urlOrDir.substring(pos + 1);
        
      • beforeLastFrontSlashPos

        🡅  🡇    
        public static java.lang.String beforeLastFrontSlashPos​
                    (java.lang.String urlOrDir)
        
        This returns the contents of a String, before the last front-slash found (including the front-slash '/' itself).

        NOTE: If no front-slash '/' character is found, then null is returned.
        Parameters:
        urlOrDir - This is any java-String, but preferably one that is a URL, or directory.
        Returns:
        the portion of the String before and including the final front-slash '/' character. If there are no front-slash characters found in this String, then null.
        Code:
        Exact Method Body:
         int pos = urlOrDir.lastIndexOf('/');
         if (pos == -1) return null;
         return urlOrDir.substring(0, pos + 1);
        
      • findLastFileSeparatorPos

        🡅  🡇    
        public static int findLastFileSeparatorPos​(java.lang.String fileOrDir)
        This function finds the position of the last 'java.io.File.separator' character in a java-String. In UNIX-based systems, this is a forward-slash '/' character, but in Windows-MSDOS, this is a back-slash '\' character. Identifying which of the two is used is obtained by "using" Java's File.separator class and field.
        Parameters:
        fileOrDir - This may be any Java-String, but preferably one that represents a file or directory.
        Returns:
        The String-index of the last 'file-separator' position in a String, or -1 if there are no such file-separators.
        Code:
        Exact Method Body:
         return fileOrDir.lastIndexOf(File.separator.charAt(0));
        
      • fromLastFileSeparatorPos

        🡅  🡇    
        public static java.lang.String fromLastFileSeparatorPos​
                    (java.lang.String fileOrDir)
        
        This returns the contents of a String, after the last 'java.io.File.separator' found.

        NOTE: If no 'java.io.File.separator' character is found, then the original String is returned.
        Parameters:
        fileOrDir - This is any java-String, but preferably one that is a filename or directory-name
        Returns:
        the portion of the String after the final 'java.io.File.separator' character. If there are no such characters found, then the original String shall be returned.
        Code:
        Exact Method Body:
         int pos = fileOrDir.lastIndexOf(File.separator.charAt(0));
         if (pos == -1) return fileOrDir;
         return fileOrDir.substring(pos + 1);
        
      • beforeLastFileSeparatorPos

        🡅  🡇    
        public static java.lang.String beforeLastFileSeparatorPos​
                    (java.lang.String urlOrDir)
        
        This returns the contents of a String, before the last 'java.io.File.separator' (including the separator itself).

        NOTE: If no 'java.io.File.separator' character is found, then null is returned.
        Parameters:
        urlOrDir - This is any java-String, but preferably one that is a URL, or directory.
        Returns:
        the portion of the String before and including the final 'java.io.File.separator' character. If there are no such characters found in this String, then null is returned.
        Code:
        Exact Method Body:
         int pos = urlOrDir.lastIndexOf(File.separator.charAt(0));
         if (pos == -1) return null;
         return urlOrDir.substring(0, pos + 1);
        
      • swapExtension

        🡅  🡇    
        public static java.lang.String swapExtension​
                    (java.lang.String fileNameOrURLWithExtension,
                     java.lang.String newExtension)
        
        This method swaps the ending 'File Extension' with another, parameter-provided, extension.
        Parameters:
        fileNameOrURLWithExtension - Any file-name (or URL) that has an extension.
        newExtension - The file or URL extension used as a substitute for the old extension. This String may begin with the dot / period character ('.'), and if it does not, one wil be appended.
        Returns:
        The new file-name or URL having the substituted extension.
        Throws:
        StringFormatException - If the String passed does not have any '.' (period) characters, then this exception will throw.

        CAUTION: In lieu of an exhaustive check on whether or not the input file-name is a valid name, this method will simply check for the presence or absence of a period-character ('.'). Checking the validity of the input name is far beyond the scope of this method.

        ALSO: This method shall check to ensure that the 'newExtension' parameter does not have length zero.

        To remove a file-extension, use removeExtension(String)
        Code:
        Exact Method Body:
         int dotPos = fileNameOrURLWithExtension.lastIndexOf('.');
        
         if (dotPos == -1) throw new StringFormatException(
             "The file-name provided\n[" + fileNameOrURLWithExtension + "]\n" +
             "does not have a file-extension"
         );
        
         if (newExtension.length() == 0) throw new StringFormatException(
             "The new file-name extension has length 0.  " +
             " To remove an extension, use 'StringParse.removeFileExtension(fileName)'"
         );
        
         return (newExtension.charAt(0) == '.')
             ? fileNameOrURLWithExtension.substring(0, dotPos) + newExtension
             : fileNameOrURLWithExtension.substring(0, dotPos) + '.' + newExtension;
        
      • removeExtension

        🡅  🡇    
        public static java.lang.String removeExtension​
                    (java.lang.String fileNameOrURL)
        
        This method simply removes all character data after the last identified period character ('.') found within fileNameOrURL.

        If the input-String does not have a period-character, the original String will be returned, unmodified.
        Parameters:
        fileNameOrURL - Any file-name or URL, as a String.
        Returns:
        The modified file-name, or URL, as a String.

        NOTE: No validity checks of any kind are performed on 'fileNameOrURL'. This method merely checks for the presence or absence of a '.' (period-character), and if it finds one, removes everything after-and-including the last-period.
        Code:
        Exact Method Body:
         int dotPos = fileNameOrURL.lastIndexOf('.');
         if (dotPos == -1) return fileNameOrURL;
         return fileNameOrURL.substring(0, dotPos);
        
      • findExtension

        🡅  🡇    
        public static int findExtension​(java.lang.String file,
                                        boolean includeDot)
        This will return the location within a String where the last period ('.') is found.

        ALSO: No validity checks for valid file-system names are performed. Rather, the portion of the input-String starting at the location of the last period is returned, regardless of what the String contains.
        Parameters:
        file - This may be any Java-String, but preferably one that represents a file.
        includeDot - When this parameter is passed TRUE, the position-index that is returned will be the location of the last index where a period ('.') is found. When FALSE, the index returned will be the location of that period + 1.
        Returns:
        This will return the location of the file-extension. If no period is found, then -1 is returned. If the period is the last char in the String, and parameter 'includeDot' is FALSE, then -1 is returned.
        Code:
        Exact Method Body:
         int pos = file.lastIndexOf('.');
        
         if (pos == -1)  return -1;
         if (includeDot) return pos;
        
         pos++;
         return (pos < file.length()) ? pos : -1;
        
      • fromExtension

        🡅  🡇    
        public static java.lang.String fromExtension​(java.lang.String file,
                                                     boolean includeDot)
        This returns the contents of a String, after the last period '.' in that String. For file-system and web files, this is often referred to as the file extension.

        NOTE: If no period '.' character is found, then null is returned.

        ALSO: No validity checks for valid file-system names are performed. Rather, the portion of the input-String starting at the location of the last period is returned, regardless of what the String contains.
        Parameters:
        file - This is any java-String, but preferably one that is a filename.
        includeDot - This determines whether the period '.' is to be included in the returned-String.
        Returns:
        the portion of the String after the final period '.' character. If parameter includeDot has been passed FALSE, then the portion of the input-String beginning after the last period is returned.

        If there are no period characters found in this String, then null is returned.
        Code:
        Exact Method Body:
         int pos = findExtension(file, includeDot);
         if (pos == -1) return null;
         return file.substring(pos);
        
      • beforeExtension

        🡅  🡇    
        public static java.lang.String beforeExtension​(java.lang.String file)
        This returns the contents of a String, before the last period '.' in that String. For file-system and web files, this is often referred to as the file extension.

        NOTE: If no period '.' character is found, then the original String is returned.

        ALSO: No validity checks for valid file-system names are performed. Rather, the portion of the input-String starting at the location of the last period is returned, regardless of what the String contains.
        Parameters:
        file - This is any java-String, but preferably one that is a filename.
        Returns:
        the portion of the String before the final period '.' character.

        If there are no period characters found in this String, then the original file is returned.
        Code:
        Exact Method Body:
         int pos = file.lastIndexOf('.');
         if (pos == -1) return file;
         return file.substring(0, pos);
        
      • findURLRoot

        🡅  🡇    
        public static java.lang.String findURLRoot​(java.lang.String url)
        This function returns the root URL-directory of a String

        SPECIFICALLY: it searches for the "last forward slash" in a String, and returns a substring from position 0 to that point. If there aren't any forward slashes in this String, null is returned. The front-slash itself is included in the returned String.

        NOTE: It is similar to the old MS-DOS call to "DIR PART"
        Parameters:
        url - Any String that is intended to be an "Internet URL" - usually http://domain/directory/[file]
        Returns:
        substring(0, index of last front-slash ('/') in String)
        Code:
        Exact Method Body:
         int pos = findLastFrontSlashPos(url);
        
         if (pos == -1)  return null;
         else            return url.substring(0, pos + 1);
        
      • firstWord

        🡅  🡇    
        public static java.lang.String firstWord​(java.lang.String s)
        Returns:
        After breaking the String by white-space, this returns the first 'chunk' before the first whitespace.
        Code:
        Exact Method Body:
         int pos = s.indexOf(" ");
        
         if (pos == -1)  return s;
         else            return s.substring(0, pos);
        
      • removeBrackets

        🡅  🡇    
        public static java.lang.String removeBrackets​(java.lang.String s)
        This function will remove any pairs of Brackets within a String, and returned the paired down String
        Parameters:
        s - Any String, which may or may not contain a "Bracket Pair"

        For Example:

        • This String does contain [a pair of brackets] within!
        • But this String does not.
        Returns:
        The same String, but with any bracket-pairs removed.
        Code:
        Exact Method Body:
         return remove_(s, '[', ']');
        
      • removeBraces

        🡅  🡇    
        public static java.lang.String removeBraces​(java.lang.String s)
        Functions the same as removeBrackets(String) - but removes pairs of curly-braces, instead
        NOTE:These are { curly braces } that will be removed by this String!
        Parameters:
        s - Any valid String { such as } - (even this String).

        For Example:

        • This String does contain {a pair of curly-braces} within!
        • But this String does not.
        Returns:
        The same String, but with any curly-brace-pairs removed.
        See Also:
        removeBrackets(String)
        Code:
        Exact Method Body:
         return remove_(s, '{', '}');
        
      • removeParens

        🡅  🡇    
        public static java.lang.String removeParens​(java.lang.String s)
        Removes Parenthesis, similar to other parenthetical removing functions.
        Parameters:
        s - Any (valid) String. Below are sample inputs:

        • This String does contain (a pair of parenthesis) within!
        • But this String does not.
        Returns:
        The same String, but with any parenthesis removed.
        See Also:
        removeBrackets(String)
        Code:
        Exact Method Body:
         return remove_(s, '(', ')');
        
      • escStrForJavaScript

        🡅  🡇    
        public static java.lang.String escStrForJavaScript​(java.lang.String str)

        Copied from Stackoverflow.com - and all the "BRILLIANT ENGINEERS"!
        Really, I wish I had a reputation!!! So awful...




        Question: String.replaceAll single backslahes with double backslashes

        I'm trying to convert the String \something\ into the String \\something\\ using replaceAll, but I keep getting all kinds of errors. I thought this was the solution:

        theString.replaceAll("\\", "\\\\");

        But this gives the below exception:

        java.util.regex.PatternSyntaxException: Unexpected internal error near index 1




        The String#replaceAll() interprets the argument as a regular expression. The \ is an escape character in both String and regex. You need to double-escape it for regex:

        string.replaceAll("\\\\", "\\\\\\\\");
        But you don't necessarily need regex for this, simply because you want an exact character-by-character replacement and you don't need patterns here. So String#replace() should suffice:

        string.replace("\\", "\\\\");

        Update: as per the comments, you appear to want to use the string in JavaScript context. You'd perhaps better use StringEscapeUtils#escapeEcmaScript() instead to cover more characters
        Parameters:
        str - This may be any String in java. It is intended to be inserted into a Java-Script file between an open and close quotation marks.
        Returns:
        The String that is returned will have certain characters escaped, so that it may be wrapped in quotation marks and easily inserted into any java-script ".js" text-file.

        Escaped-Text:

        • char '\' will be escaped to: "\\"
        • char '/' will be escaped to: "\/", this is required in Java-Script, but not Java!
        • char '"' will be escaped to: "\""
        • char '\n' will be escaped to: "\\n"

        IMPORTANT NOTE: There is no easy, nor clear, way to express what is being replaced and/or escaped in a simple list. You may run this method on any String and view for yourself what changes. The primary goal of the method is to allow *any* Java String of *any* length to be converted, wrapped inside of an open and closed quotation-marks, and printed into a Java-Script ".js" file. Escaping "escape characters" which does come up some-what often in HTML text/string processing is near-impossible to explain clearly! Review the stack-overflow "incantation" for possible help.
        Code:
        Exact Method Body:
         return StrReplace.r(str, JS_ESCAPE_CHARS, '\\');
        
      • escStrForRegEx

        🡅  🡇    
        public static java.lang.String escStrForRegEx​(java.lang.String str)
        This method should only be used for a precise String match using a regular-expression. This method shall 'escape' all characters that the JVM Regular Expression Matcher in package java.util.regex.* would expect be escaped. If the input parameter 'str' contains any regular-expression code, then this method would FAIL as it would escape regular-expression code into unusable text.
        Parameters:
        str - This should be any String for which the user would like to find an exact match, as-is.
        Returns:
        A regular-expression ready String
        Code:
        Exact Method Body:
         return StrReplace.r(str, REGEX_ESCAPE_CHARS, '\\');
        
      • objToB64Str

        🡅  🡇    
        public static java.lang.String objToB64Str​(java.lang.Object o)
                                            throws java.io.IOException
        This will convert any Serializable Java Object into a base-64 String. This String may be saved, transmitted, even e-mailed to another party, if you wish and decoded else-where.

        REQUIREMENTS:

        1. Object must implement the interface java.io.Serializable
        2. Receiving party or storage-device must have access to the .jar file, or .class file(s) needed to instantiate that object! (You must have shared your classes if you intend to let other people de-serialize instances of that class)
        Parameters:
        o - Any java java.lang.Object. This object must be Serializable, or else the code will generate an exception.
        Returns:
        A String version of this object. It will be:

        1. Serialized using the java.io.ObjectOutputStream(...) object-serialization method
        2. Compressed using the java.io.GZIPOutputStream(...) stream-compression method
        3. Encoded to a String, via Base-64 Encoding java.util.Base64.getEncoder()

        NOTE: Compression does not always make much difference, however often times when doing web-scraping projects, there are large Java java.util.Vector<String> filled with many lines of text, and these lists may be instantly and easily saved using object-serialization. Furthermore, in these cases, the compression will sometimes reduce file-size by an order of magnitude.
        Throws:
        java.io.IOException
        See Also:
        b64StrToObj(String)
        Code:
        Exact Method Body:
         ByteArrayOutputStream   bos     = new ByteArrayOutputStream();
         GZIPOutputStream        gzip    = new GZIPOutputStream(bos);
         ObjectOutputStream      oos     = new ObjectOutputStream(gzip);
        
         oos.writeObject(o); oos.flush(); gzip.finish(); oos.close(); bos.close();
        
         return Base64.getEncoder().encodeToString(bos.toByteArray());
        
      • b64StrToObj

        🡅  🡇    
        public static java.lang.Object b64StrToObj​(java.lang.String str)
                                            throws java.io.IOException
        This converts to any java.io.Serializable object from a compressed, serialized, Base-64 Encoded java.lang.String. This method can be thought of as one which converts objects which have been previously encoded as a String, and possibly even transmitted across the internet, back into an Java Object.

        REQUIREMENTS: The Object that is to be instantiated must have its class files accessible to the class-loader. This is the exact-same requirement expected by all Java "de-serializations" routines.
        Parameters:
        str - Any previously Base-64 encoded, serialized, compressed java.lang.Object' that has been saved as a String. That String should have been generated using the Programming.objToB64Str(Object o) method in this class.

        1. Serialized using the java.io.ObjectOutputStream(...) object-serialization method
        2. Compressed using the java.io.GZIPOutputStream(...) sream-compression method
        3. Encoded to a String, via Base-64 Encoding java.util.Base64.getEncoder()

        NOTE: Compression does not always make much difference, however often times when doing web-scraping projects, there are large Java java.util.Vector<String> filled with many lines of text, and these lists may be instantly and easily saved using object-serialization. Furthermore, in these cases, the compression will sometimes reduce file-size by an order of magnitude.
        Returns:
        The de-compressed java.lang.Object converted back from a String.
        Throws:
        java.io.IOException
        See Also:
        objToB64Str(Object)
        Code:
        Exact Method Body:
         ByteArrayInputStream    bis     = new ByteArrayInputStream(Base64.getDecoder().decode(str));
         GZIPInputStream         gzip    = new GZIPInputStream(bis);
         ObjectInputStream       ois     = new ObjectInputStream(gzip);
         Object                  ret     = null;
        
         try
             { ret = ois.readObject(); }
         catch (ClassNotFoundException e)
         {
             throw new IOException(
                 "There were no serialized objects found in your String.  See e.getCause();",
                 e
             );
         }
        
         bis.close(); ois.close();
         return ret;
        
      • objToB64MimeStr

        🡅  🡇    
        public static java.lang.String objToB64MimeStr​(java.lang.Object o)
                                                throws java.io.IOException
        This performs an identical operation as the method: objToB64Str, however it generates an output String that is "MIME" compatible. All this means is that the String itself - which could conceivable by thousands or even hundreds of thousands of characters long - will have new-line characters inserted such that it may be printed on paper or included in a text-file that is (slightly) more human-readable. Base64 MIME encoded String's look like very long paragraphs of random-text data, while regular Base64-encodings are a single, very-long, String with no space characters.
        Parameters:
        o - Any java.lang.Object. This object must be Serializable, or else the code will generate an exception.
        Returns:
        A Base-64 MIME Encoded String version of any serializable java.lang.Object.
        Throws:
        java.io.IOException
        See Also:
        objToB64Str(Object), b64MimeStrToObj(String)
        Code:
        Exact Method Body:
         ByteArrayOutputStream   bos     = new ByteArrayOutputStream();
         GZIPOutputStream        gzip    = new GZIPOutputStream(bos);
         ObjectOutputStream      oos     = new ObjectOutputStream(gzip);
        
         oos.writeObject(o); oos.flush(); gzip.finish(); oos.close(); bos.close();
        
         return Base64.getMimeEncoder().encodeToString(bos.toByteArray());
        
      • b64MimeStrToObj

        🡅  🡇    
        public static java.lang.Object b64MimeStrToObj​(java.lang.String str)
                                                throws java.io.IOException
        This performs an identical operation as the method: b64StrToObj, however receives a "MIME" compatible encoded String. All this means is that the String itself - which could conceivable by thousands or even hundreds of thousands of characters long - will have new-line characters inserted such that it may be printed on paper or included in a text-file that is (slightly) more human-readable. Base64 MIME encoded String's look like very long paragraphs of random-text data, while regular Base64 encodings a single, very-long, String's.
        Returns:
        The (de-serialized) java object that was read from the input parameter String 'str'

        REQUIREMENTS: The object that is to be instantiated must have its class files accessible to the class-loader. This is the exact-same requirement expected by all Java "de-serializations" routines.
        Throws:
        java.io.IOException
        See Also:
        b64StrToObj(String), objToB64MimeStr(Object)
        Code:
        Exact Method Body:
         ByteArrayInputStream    bis     = new ByteArrayInputStream(Base64.getMimeDecoder().decode(str));
         GZIPInputStream         gzip    = new GZIPInputStream(bis);
         ObjectInputStream       ois     = new ObjectInputStream(gzip);
         Object                  ret     = null;
        
         try
             { ret = ois.readObject(); }
         catch (ClassNotFoundException e)
         { 
             throw new IOException(
                 "There were no serialized objects found in your String.  See e.getCause();",
                 e
             );
         }
        
         bis.close(); ois.close();
         return ret;
        
      • dotDots

        🡅  🡇    
        public static java.lang.String dotDots​(java.lang.String fileName,
                                               java.lang.String ancestorDirectory,
                                               char separator)
        Computes a "relative URL String".
        Parameters:
        fileName - This is a fileName whose ancestor directory needs to be 'relative-ised'
        ancestorDirectory - This is an ancestor (container) directory.
        separator - The separator character used to separate file-system directory names.
        Returns:
        This shall return the "../.." structure needed to insert a relative-URL or link into a web-page.
        Throws:
        java.lang.IllegalArgumentException - This exception shall throw if the separator character is not one of the standard file & directory separators: forward-slash '/' or back-slash '\'.

        This exception also throws if the String provided to parameter 'fileName' does not begin-with the String provided to parameter 'ancestorDirectory'.
        Code:
        Exact Method Body:
         if ((separator != '/') && (separator != '\\')) throw new IllegalArgumentException(
             "The separator character provided to this method must be either a forward-slash '/' " +
             "or a back-slash ('\\') character.  You have provided: ['" + separator + "']."
         );
        
         if (! fileName.startsWith(ancestorDirectory)) throw new IllegalArgumentException(
             "The file-name you have provided [" + fileName + "] is a String that does " +
             "start with the ancestorDirectory String [" + ancestorDirectory + "].  " +
             "Therefore there is no relative path using the dot-dot construct to the named " +
             "ancestor directory fromm the directory where the named file resides."
         );
        
         int levelsDeep = StringParse.countCharacters(fileName, separator) - 
             StringParse.countCharacters(ancestorDirectory, separator);
        
         String dotDots = "";
        
         while (levelsDeep-- > 0) dotDots = dotDots + ".." + separator;
        
         return dotDots;
        
      • dotDotParentDirectory

        🡅  🡇    
        public static java.lang.String dotDotParentDirectory​(java.net.URL url)
        Convenience Method
        Invokes: dotDotParentDirectory(String, char, short)
        Converts: URL to String, eliminates non-essential URI-information (Such as: ASP, JSP, PHP Query-Strings, and others too)
        Passes: char '/', the separator character used in URL's
        Passes: '1' to parameter 'nLevels' - only going up on directory
        Code:
        Exact Method Body:
         String urlStr = url.getProtocol() + "://" + url.getHost() + url.getPath();
         return dotDotParentDirectory(urlStr, '/', (short) 1);
        
      • dotDotParentDirectory

        🡅  🡇    
        public static java.lang.String dotDotParentDirectory​
                    (java.lang.String urlAsStr)
        
        Convenience Method
        Invokes: dotDotParentDirectory(String, char, short)
        Passes: char '/', the separator character used in URL's
        Passes: '1' to parameter 'nLevels' - only going up on directory
        Code:
        Exact Method Body:
         return dotDotParentDirectory(urlAsStr, '/', (short) 1);
        
      • dotDotParentDirectory

        🡅  🡇    
        public static java.lang.String dotDotParentDirectory​(java.net.URL url,
                                                             short nLevels)
        Convenience Method
        Invokes: dotDotParentDirectory(String, char, short)
        Converts: URL to String, eliminates non-essential URI-information (Such as: ASP, JSP, PHP Query-Strings, and others too)
        Passes: char '/', the separator character used in URL's
        Code:
        Exact Method Body:
         String urlStr = url.getProtocol() + "://" + url.getHost() + url.getPath();
         return dotDotParentDirectory(urlStr, '/', nLevels);
        
      • dotDotParentDirectory

        🡅  🡇    
        public static java.lang.String dotDotParentDirectory​
                    (java.lang.String directoryStr,
                     char dirSeparator)
        
        Convenience Method
        Invokes: dotDotParentDirectory(String, char, short).
        Passes: '1' to parameter nLevels - only going up one directory.
        Code:
        Exact Method Body:
         return dotDotParentDirectory(directoryStr, dirSeparator, (short) 1);
        
      • dotDotParentDirectory

        🡅  🡇    
        public static java.lang.String dotDotParentDirectory​
                    (java.lang.String directoryStr,
                     char separator,
                     short nLevels)
        
        This does traverses up a directory-tree structure, and returns a 'parent-level' directory that is 'nLevels' up the tree.

        NOTE: The character used as the "File Separator" and/or "Directory Separator" can be obtained using the field: java.io.File.Separator.charAt(0). The class java.io.File provides access to the file-separator used by the file-system on which the JVM is currently running, although it treats it as a multi-character String. Just use the commonly-used java method 'charAt(0)' to obtain the forward-slash '/' or backward-slash '\' character.

        IMPORTANT: There is no error-checking performed by this method regarding whether the input String represents a valid file or directory. Instead, this method just looks for the second from last separator-character (usually a '/' forward-slash char) and returns a substring that starts at index 0, and continues to that position-plus-1 (in order to include that second-to-last separator char).
        Parameters:
        directoryStr - This may be any java-String, although it is expected to be on which represents the file & directory structure of file on the file-system. It may also be URL for a web-site
        separator - This is the separator currently used by that file & directory system. If trying to find the parent directory of a URL, this should be the forward-slash character '/'.
        nLevels - This is how many "parent-level directories" (how many levels up the tree) need to be computed. This parameter must '1' or greater. If the passed parameter 'directoryStr' does not contain enough directories to traverse up the tree, then this method will throw an IllegalArgumentException.
        Returns:
        a String that represents 'nLevels' up the directory tree, either for a directory on the local-file system, or on a web-server from a Uniform Resource Locator.
        Throws:
        java.lang.IllegalArgumentException - If the value of parameter short 'nLevels' is negative, or does not identify a number consistent with the number of directories that are contained by the input urlAsStr parameter.

        This exception shall also throw if the 'separator' character is not one of the standard file & directory separators: forward-slash '/' or back-slash '\'.
        Code:
        Exact Method Body:
         if (nLevels < 1) throw new IllegalArgumentException(
             "The parameter nLevels may not be less than 1, nor negative.  You have passed: " + nLevels
         );
        
         if ((separator != '/') && (separator != '\\')) throw new IllegalArgumentException(
             "The separator character provided to this method must be either a forward-slash '/' " +
             "or a back-slash ('\\') character.  You have provided: ['" + separator + "']."
         );
        
         int count = 0;
        
         for (int i=directoryStr.length() - 1; i >= 0; i--)
             if (directoryStr.charAt(i) == separator)
                 if (++count == (nLevels + 1))
                     return directoryStr.substring(0, i + 1);
        
         throw new IllegalArgumentException(
             "The parameter nLevels was: " + nLevels + ", but unfortunately there only were: " + count +
             "'" + separator + "' characters found in the directory-string."
         );
        
      • trimEachLine

        🡅  🡇    
        public static java.lang.String trimEachLine​(java.lang.String str)
        This is used for "trimming each line" of an input String. Generally, when dealing with HTML there may be superfluous white-space that is useful in some places, but not necessarily when HTML is copied and pasted to other sections of a page (or to another page, altogether). This will split a String by new-line characters, and then trim each line, and afterward rebuild the String and return it.

        NOTE: This will only split the String using the standard '\n' character. If the String being used uses '\r' or '\n\r', use a different trim.
        Parameters:
        str - This may be any String. It will be split by new-line characters '\n'
        Returns:
        Returns the rebuilt String, with each line having a String.trim(); operation performed.
        Code:
        Exact Method Body:
         StringBuilder sb = new StringBuilder();
        
         for (String s : str.split("\\n"))
        
             if ((s = s.trim()).length() == 0)   continue;
             else                                sb.append(s + '\n');
        
         return sb.toString().trim();
        
      • parseGenericType

        🡅  🡇    
        public static java.lang.String[] parseGenericType​
                    (java.lang.String genericTypeParamOrDefinition)
        
        Parses a String such as T extends TreeMap<Integer, List<String>>. It is strictly used, to only parse the generic-definition lists that are at the top of generic classes and interfaces.

        Sample Input StringOutput String[] array
        "HashMap<E extends Comparable, F extends Comparable>" { "E extends Comparable", "F extends Comparable" }
        "Ret6<A, B, C, D, E, F>" { "A", "B", "C", "D", "E", "F" }
        "AbstractHNLI<?, Vector<Vector<? extends HTMLNode>>>" { "?", "Vector<Vector<? extends HTMLNode>>" }
        "VarList<Vector<HashMap<String, String>>, FileNode>" { "Vector<HashMap<String, String>>", "FileNode" }
        Parameters:
        genericTypeParamOrDefinition - This should be String retrieved from inside the less-than ('<') and greater-than ('>') symbols. For example, for SortedList<A extends Comparable, B> the String passed to this method should be "A extends Comparable, B"
        Returns:
        This should break down this CSV (comma separated value) list into individual String's.
        Throws:
        NoMatchException - if the input String parameter does not match the generics regular-expression GENERIC_PARAMS.
        StringFormatException - If the input String could not be parsed.
        Code:
        Exact Method Body:
         Matcher m               = GENERIC_PARAMS.matcher(genericTypeParamOrDefinition);
         String  innerGenericStr = m.find() ? m.group(1) : null;
        
         if (innerGenericStr == null) throw new NoMatchException(
             "The provided value to parameter 'genericTypeParamOrDefinition' [" + 
             genericTypeParamOrDefinition + "] did not match the Java Generics " +
             "Regular-Expression:\n" + GENERIC_PARAMS.toString()
         );
        
         Stream.Builder<String>  b               = Stream.builder();
         String[]                sArr            = innerGenericStr.split(",");
        
         for (int i=0; i < sArr.length; i++)
        
             // We have shifted elements, and now all of the remaining elements would be null
             // return immediately
             if (sArr[i] == null) return b.build().toArray(String[]::new);
        
             // Simple generic-type definition: has no "sub-generics" or "inner-generics"
             // Add this to the list, and move on,
             else if ((! sArr[i].contains("<")) && (! sArr[i].contains(">")))
                 b.accept(sArr[i].trim());
        
             // This is a generic-type definition that has at least one "sub-generic"
             // If there are an equal number of '<' and '>' then there were no commas
             // in between the sub-generics.  Add this to this list, and move on.
             else if (countCharacters(sArr[i], '<') == countCharacters(sArr[i], '>'))
                 b.accept(sArr[i].trim());
        
             // There was a generic with a sub-generic that had a comma...
             else
             {
                 // If we have reached the end of the String, the number of greater than and
                 // less than symbols was not balanced.
                 if (i == (sArr.length - 1)) throw new StringFormatException(
                     "The provided value to parameter 'genericTypeParamOrDefinition' [" + 
                     genericTypeParamOrDefinition + "], was not properly formatted, and could " +
                     "not be parsed."
                 );
        
                 // Join the next String Array Element with the current one.
                 sArr[i] = sArr[i].trim() + ", " + sArr[i + 1].trim();
        
                 // Shift the rest of the array left.
                 for (int j=i+1; j < (sArr.length-1); j++) sArr[j] = sArr[j+1];
                 sArr[sArr.length - 1] = null;
        
                 // decrement the counter to retest this array-index location
                 i--;
             }
        
         // Return the list
         return b.build().toArray(String[]::new);
        
      • caretBeneath

        🡅  🡇    
        public static java.lang.String caretBeneath​(java.lang.String str,
                                                    int strPos)
        This will print a caret-symbol on a line of text underneath the input String parameter 'str'. Preceeding the caret-symbol will be exactly strPos - 1 space characters. This look of the output-String is similar to some of the error messages generated by a Java Compiler.

        The caret-symbol '^' will bee pointing to the character at index strPos.

        Example:
         // Notice the (accidental, on-purpose) use of the '@'' character instead of an 'a'
         // To make this easy, lets compute the exact location of this erroneous character.
         String   s   = "This string has an inv@lid character.";
         int      pos = s.indexOf("@");
         
         // This will print out a line of text containing the string, with a caret pointing
         // at the '@' symbol.
         System.out.println(StringParse.caretBeneath(s, pos));
        
         // PRINTS:
         // This string has an inv@lid character.
         //                       ^
        
        Parameters:
        str - This may be any input-String that is less than 100 characters.
        strPos - This must be a number between 0 and the length
        Returns:
        The same input-String with a second line appended underneath (using a newline) having a caret ('^') directly underneath the character at strPos.
        Throws:
        java.lang.IllegalArgumentException - If the input String is longer than 100 characters.
        StringFormatException - If the input String contains any new-line '\n' or tab '\t' characters.
        java.lang.StringIndexOutOfBoundsException - If the value pased to strPos is negative or greater than the length of the input-String.
        See Also:
        nChars(char,int)
        Code:
        Exact Method Body:
         if (str.length() > 100) throw new IllegalArgumentException(
             "The length of the input-string must be less than 100.  str has length: " +
             str.length()
         );
        
         if (StrCmpr.containsOR(str, "\n", "\t")) throw new StringFormatException
             ("The input-string may not contain new-line or tab characters.");
        
         if (strPos >= str.length()) throw new StringIndexOutOfBoundsException(
             "The value you have passed to 'strPos' [" + strPos + "] is greater than the length " +
             "the input-string [" + str.length() + "]"
         );
        
         if (strPos < 0) throw new StringIndexOutOfBoundsException
             ("You have passed a negative value to strPos [" + strPos + "]");
        
         return str + "\n" + nChars(' ', strPos) + '^';
        
      • removeGeneric

        🡅  🡇    
        public static java.lang.String removeGeneric​(java.lang.String typeAsStr)
        This will remove the generic type-parameters expression from a Java Type Declaration or Reference. In simple terms, this removes the '<K, V>' from a String such as Map.Entry<K, V>.
        Returned String Input String
        "Vector" "Vector<E>""
        "AbstractHNLI" "AbstractHNLI<E extends HTMLNode, F>"
        "Torello.HTML.TagNode" "Torello.HTML.TagNode"
        "ClassA.InnerClassB.InnerClassC" "ClassA<X>.InnerClassB<Y>.InnerClassC"
        "String[]" "String[]"
        "java.lang.String[]" "java.lang.String[]"
        "Vector" "Vector<String[]>"
        "java.util.Vector" "java.util.Vector<String[]>"
        NOTE:
        "I watched the World Series" "I watched the World Series"
        "Vector" "Vector"
        Throws an Exception
        "HNLI<E> <"
        "> <Quoth the Raven>"
        Parameters:
        typeAsStr - The "Reference Type" or "Declaration Type".
        Returns:
        The same String, having everything between the outer-most, matching '<' and '>' symbols.

        NOTE: The returned String will not contain any leading or trailing white-space. It is trimmed before being returned.
        Throws:
        StringFormatException - An exhaustive check on everything that could be wrong with a type-String is an impossibility (if you include checking for valid types). This exception is only thrown if the '<' and '>' symbols inside the input-String do not match-up.

        In order to avoid throwing this exception, there must be an equal number of opening and closing symbols.

        There is also a check to ensure that the charcters in this String are valid.
        Code:
        Exact Method Body:
         int leftPos = typeAsStr.indexOf('<');
        
         if (leftPos == -1)
         {
             int pos = typeAsStr.indexOf('>');
        
             if (pos == -1) return typeAsStr.trim();
        
             throw REM_GENERIC_ERROR_MSG(typeAsStr, pos);
         }
        
         char[]  cArr    = typeAsStr.toCharArray();
         int     count   = 1;            // The number of OPENING-CLOSING tags (same as Inclusive)
         int     END     = cArr.length;  // This is the location JUST-AFTER the last USEABLE-char
         int     delta   = 0;            // How many characters have been deleted already.
                                         // NOTE: This is zero, because the loop hasn't started.
                                         //       If there is a "Shift" this will be PRECISELY-EQUAL
                                         //       to the size of the last generic parameter-expression.
                                         // ALSO: The only purpose of this is for error-reporting.
        
         // check for a closing '>' before the first opening '<'
         for (int j=0; j < leftPos; j++)
             if (cArr[j] == '>') throw REM_GENERIC_ERROR_MSG(typeAsStr, j);
        
         // Check for in-valid characters
         // This is a lot of lines of code, but these methods are extremely short, and the input
         // string (for all VALID) input will be very short.  This is peace of mind.  It checks...
         for (int pos=0; pos < cArr.length; pos++)
         {
             char c = cArr[pos];
             if (! Character.isJavaIdentifierPart(c))
                 if (! Character.isIdentifierIgnorable(c))
                     if (! Character.isWhitespace(c))
                         if (
                                 (c != '[') && (c != ']') && (c != '?') && (c != '<') &&
                                 (c != '>') && (c != ',') && (c != '.')
                         )
                             throw REM_GENERIC_ERROR_MSG(typeAsStr, pos);
         }
        
         do
         {
             // Keeps a count on the number of "Opening Braces" and "Closing Braces" 
             // This is the same thing as the whole "Inclusive" deal, but with braces instead.
             //
             // count: At loop start, count is '1'  If it ever reaches 0, the loop exits.
             // leftPos: The location of the '<' that has been found.
             int i = leftPos + 1;
            
             while ((count > 0) && (i < END))
             {
                 if      (cArr[i] == '<')    count++;
                 else if (cArr[i] == '>')    count--;
        
                 if (count > 0) i++;
             }
        
             // The '<' and the '>' didn't match up.  Better to throw exception, than ignore it.
             if ((count != 0) && (i == END))
                 throw REM_GENERIC_ERROR_MSG(typeAsStr, leftPos);
        
             int rightPos = i; // 'i' is currently pointing to the '>'
        
             // Erase the most recently found <...> expression
             int     sourcePos       = rightPos + 1; // Pointing at first VALID / NEED-TO-COPY char
             int     destPos         = leftPos;      // Pointing at '<'
             boolean possiblyAnother = false;
        
             while (sourcePos < END)
             {
                 // The next character to copy... check it first to see if it is valid!
                 char c = cArr[sourcePos]; 
        
                 // continue to shift all the characters left to erase the expression.
                 cArr[destPos] = c;
        
                 if (! possiblyAnother) // Haven't found an opening '<'
                 {
                     // If there is a '>' - ***AND NO '<' HAS BEEN FOUND***, this is an error.    
                     if (c == '>')
                         throw REM_GENERIC_ERROR_MSG(typeAsStr, delta + sourcePos);
        
                     // If there is another '<', then it is possible another expression awaits us
                     if (c == '<')
                     {
                         // Reset the outer-loop variables for the next iteration.  There is going
                         // to be another iteration - guaranteed.
                         //
                         // NOTE: Delta is supposed to hold how many characters are being deleted.
                         //       This is used for proper error-reporting (only)
        
                         // This is how many chars are in the current <...> expression
                         delta   = rightPos - leftPos + 1;
        
                         leftPos = destPos;  // Now pointing at the next open '<' char (just found!)
                         count   = 1;        // There was a new-unclosed '>', prepares for next loop
        
                         // You know it
                         possiblyAnother = true;
                     }
                 }
        
                 sourcePos++; destPos++;
             }
        
             // Completed without errors, and without another expression being found.
             // NOTE: This used to be a one-line return call.
             // ADDED: This now does a String.trim().   These little loops skip leading and 
             //        trailing white-space BEFORE returning the String
             //
             // WORKS-NO-TRIM: return new String(cArr, 0, destPos);
             //                replace loop-body with the above line to get rid of trim()
             if (! possiblyAnother)
             {
                 int sPos    = 0;
                 int len     = destPos;  // REMEMBER:    new String(char[], int OFFSET, int COUNT)
                                         // NOT:         new String(char[], int SPOS, int EPOS)
        
                 // Skip LEADING-WHITESPACE
                 while ((sPos < cArr.length) && (destPos > 0) && Character.isWhitespace(cArr[sPos]))
                 { sPos++; destPos--; } // Advance start, *AND* shorten "count"
        
                 // Skip TRAILING WHITE-SPACE
                 while ((destPos > 1) && Character.isWhitespace(cArr[sPos + destPos-1]))
                     destPos--; // Shorten length *ONLY*
        
                 return new String(cArr, sPos, destPos);
             }
                    
             END = destPos;  // Pointing at the first invalid / unused / ALREADY-MOVED char
         }
         while (true);
        
      • typeToJavaIdentifier

        🡅  🡇    
        public static java.lang.String typeToJavaIdentifier​
                    (java.lang.String typeStr)
        
        This will remove any generic-parameter information from a Java type-String and then remove all package-information or outer-class String's. What is left is a single Java Identifier String that, as long as the proper scope has been provided, identifies a Java Type (Class, Interface, Enum, Record, Annotation).
        OutputInput
        "Integer""java.lang.Integer"
        "Vector""java.util.Vector<E>"
        "Entry""java.util.Map.Entry<String, Integer>"
        "Entry""Map.Entry<String, Intger>"
        "Entry""Entry<String, Integer>"
        "Entry""Entry"
        "String[]""String[]"
        "String[]""java.lang.String[]"
        "Vector""Vector<String[]>"
        "Vector[]""Vector<String>[]"
        NOTE:
        "The World Series""The World Series"
        "Quoth the Raven""Quoth the Raven<java.lang.Integer>"
        Parameters:
        typeStr - This is a type as a String. These are usually retrieved from Java Parser, in the Java Doc Upgrader package. This method does not provide an exhaustive check for all variants of format and naming erros of a Java Type. Some validity checks are performed regarding the use of non-Java type characters.

        NOTE: All the exceptions thrown by the method removeGeneric(String) will also be thrown here, if 'typeStr' is not not properly formatted.
        Returns:
        a Simplified version of the type that leaves out the scope, but provides a simple Java Identifier, instead. Throws exceptions if not properly formatted. If any array-bracket characters are passed, they is preserved, unless the arrays in this type are part of the generic-type parameters; please see the examples above.
        Throws:
        StringFormatException - Please see the explanation provided in removeGeneric(String) under 'Throws'.
        See Also:
        removeGeneric(String)
        Code:
        Exact Method Body:
         String  ret = removeGeneric(typeStr);
         int     pos = ret.lastIndexOf('.');
        
         if (pos == -1)  return ret;
         else            return ret.substring(pos+1);
        
      • removeExtendsClause

        🡅  🡇    
        public static java.lang.String removeExtendsClause​(java.lang.String decl)
        Removes the 'extends' part of a Java Generic

        TO DO: This will fail for a class such as:
        public class MyClass<T extends Vector<String>, where the extends clause also has a generic in it. Java HTML does not define such classes, but they are possible, and this needs to be fixed, as soon as they let me!
        Parameters:
        decl - Any Type Declaration that includes has the word {'extends'}, followed by type-parameter information.
        Returns:
        The same String without the clause.
        Code:
        Exact Method Body:
         Matcher m = exClause.matcher(decl);
        
         while (m.find())
         {
             decl = m.replaceFirst(m.group(1));
             m.reset(decl);
         }
        
         return decl;
        
      • replaceNBSP

        🡅  🡇    
        public static java.lang.String replaceNBSP​(java.lang.String s)
        There are actually people out there who are willing to put character '160' into a file or document, instead of a simple '&nbsp;' element. How rude. Any instances of this character shall be replaced with the standard space character ASCII #32.
        Parameters:
        s - Any String will pass. Generally String's that were converted from HTML pages will contain char #160 as it is occasionally translated from the HTML escape sequence &nbsp;
        Returns:
        A String where any instance of white-space character #160 have been replaced with character #32
        Code:
        Exact Method Body:
         return s.replace(("" + ((char) 160)), " ");
        
      • replaceZWSP

        🡅  🡇    
        public static java.lang.String replaceZWSP​(java.lang.String s)
        Even lower than #160, apparently is the "Zero Width Space" (character #8203. This is actually inserted by the JavaDoc Tool (by Sun / Oracle) into JavaDoc generated HTML Pages. Here, it shall be replaced by character #32 - the space-character.

        A.K.A.: "‚Äč".

        Can you see the character, above? No? That's zero width space for you! If you ever sitting and wondering why a String seems to be something else than what it looks like - you might have a zero-width space in your String. If so, it will take a while to find the bug.
        Parameters:
        s - Any String will pass. Generally String's that were converted from JavaDoc HTML pages will contain char #8203.
        Returns:
        A String where any instance of white-space character #8203 have been replaced with character #32
        Code:
        Exact Method Body:
         return s.replace(("" + ((char) 8203)), " ");
        
      • firstNLines

        🡅  🡇    
        public static java.lang.String firstNLines​(java.lang.String s,
                                                   int n)
        This will retrieve the first 'n' lines of a String - where a line is defined as everything up to and including the next newline '\n' character.
        Parameters:
        s - Any java String.
        n - This is the number of lines of text to retrieve.
        Returns:
        a substring of s where the last character in the String is a '\n'. The last character should be the nth '\n' character found in s. If there is no such character, then the original String shall be returned instead.
        Throws:
        NException - This exception shall throw if parameter 'n' is less than 1, or longer than s.length().
        Code:
        Exact Method Body:
         NException.check(n, s);
         int pos = StrIndexOf.nth(s, n, '\n');
        
         if (pos != -1)  return s.substring(0, pos + 1);
         else            return s;
        
      • lastNLines

        🡅  🡇    
        public static java.lang.String lastNLines​(java.lang.String s,
                                                  int n)
        This will retrieve the last 'n' lines of a String - where a line is defined as everything up to and including the next newline '\n' character.
        Parameters:
        s - Any java String.
        n - This is the number of lines of text to retrieve.
        Returns:
        a substring of 's' where the last character in the String is a new-line character '\n', and the first character is the character directly before the nth newline '\n' found in 's' - starting the count at the end of the String. If there is no such substring, then the original String shall be returned.
        Throws:
        NException - This exception shall throw if 'n' is less than 1, or longer s.length().
        Code:
        Exact Method Body:
         NException.check(n, s);
         int pos = StrIndexOf.nthFromEnd(s, n, '\n');
        
         if (pos != -1)  return s.substring(pos + 1);
         else            return s;
        
      • isInteger

        🡅  🡇    
        public static boolean isInteger​(java.lang.String s)
        Determines, efficiently, whether an input String is also an integer.

        NOTE: A leading plus-sign ('+') will, in fact, generate a FALSE return-value for this method.
        Parameters:
        s - Any java String
        Returns:
        TRUE if the input String is any integer, and false otherwise.

        NOTE: This method does not check whether the number, itself, will actually fit into a field or variable of type 'int'. For example, the input String '12345678901234567890' (a very large integer), though an integer from a mathematical perspective, is not a valid java 'int'. In such cases, TRUE is returned, but if Java's Integer.parseInt method were subsequently used, that method would throw an exception.

        NOTE: The primary purpose of this method is to avoid having to write try {} catch (NumberFormatException) code-blocks. Furthermore, if only a check is desired, and the String does not actually need to be converted to a number, this is also more efficient than actually performing the conversion.
        See Also:
        isInt(String)
        Code:
        Exact Method Body:
         if (s == null) return false;
        
         int length = s.length();
        
         if (length == 0) return false;
        
         int i = 0;
        
         if (s.charAt(0) == '-')
         {
             if (length == 1) return false;
             i = 1;
         }
        
         while (i < length)
         {
             char c = s.charAt(i++);
             if (c < '0' || c > '9') return false;
         }
        
         return true;
        
      • isInt

        🡅  🡇    
        public static boolean isInt​(java.lang.String s)
        Convenience Method
        Invokes: isOfPrimitiveType(String, char[])
        Passes: The ASCII characters that comprise Integer.MIN_VALUE
        Code:
        Exact Method Body:
         return isOfPrimitiveType(s, INT_MIN_VALUE_DIGITS_AS_CHARS);
        
      • isLong

        🡅  🡇    
        public static boolean isLong​(java.lang.String s)
        Convenience Method
        Invokes: isOfPrimitiveType(String, char[])
        Passes: The ASCII characters that comprise Long.MIN_VALUE
        Code:
        Exact Method Body:
         return isOfPrimitiveType(s, LONG_MIN_VALUE_DIGITS_AS_CHARS);
        
      • isByte

        🡅  🡇    
        public static boolean isByte​(java.lang.String s)
        Convenience Method
        Invokes: isOfPrimitiveType(String, char[])
        Passes: ASCII characters that comprise Byte.MIN_VALUE
        Code:
        Exact Method Body:
         return isOfPrimitiveType(s, BYTE_MIN_VALUE_DIGITS_AS_CHARS);
        
      • isShort

        🡅  🡇    
        public static boolean isShort​(java.lang.String s)
        Convenience Method
        Invokes: isOfPrimitiveType(String, char[])
        Passes: ASCII characters that comprise Short.MIN_VALUE
        Code:
        Exact Method Body:
         return isOfPrimitiveType(s, SHORT_MIN_VALUE_DIGITS_AS_CHARS);
        
      • isOfPrimitiveType

        🡅  🡇    
        protected static boolean isOfPrimitiveType​(java.lang.String s,
                                                   char[] minArr)
        Determines whether the input String is an integer in the range of Java's primitive type specified by an input char[] array parameter. Specifically, if the the input String is both a mathematical integer, and also an integer in the range of MIN_VALUE and MAX_VALUE for that primitive-type and then (and only then) will TRUE be returned.

        NOTE: The max and min values in which the range of valid integers must reside (for primitive-type 'int', for instance) are as below: -2147483648 ... 2147483647.

        ALSO: A leading plus-sign ('+') will, in fact, generate a FALSE return-value for this method.
        Parameters:
        s - Any Java String
        minArr - The value of a Java Primitive MIN_VALUE, without the minus-sign, represented as a char[] array.
        Primitive Type Integer as ASCII char[] array
        byte '2', '5', '6'
        short '6', '5', '5', '3', '6'
        int '2', '1', '4', '7,' '4', '8', '3', '6', '4', '8'
        long '2', '1', '4', '9', '2', '2', '3', '3', '7', '2', '0', '3', '6', '8', '5', '4', '7', '7', '5', '8', '0', '8'
        Returns:
        TRUE If the input String is both an integer, and also one which falls in the range comprised by the specified Java Primitive Type. Return FALSE otherwise.

        NOTE: The primary purpose of this method is to avoid having to write try {} catch (NumberFormatException) code-blocks. Furthermore, if only a check is desired, and the String does not actually need to be converted to a number, this is also more efficient than actually performing the conversion.
        See Also:
        isInteger(String), isInt(String), isByte(String), isLong(String), isShort(String)
        Code:
        Exact Method Body:
         int length = s.length();
        
         // Zero length string's are not valid integers.
         if (length == 0)                                    return false;
        
         // A negative integer may begin with a minus-sign.
         boolean negative = s.charAt(0) == '-';
        
         // ****************************************************************************************
         // If the string is too short or too long, this method doesn't need to do any work.
         // We either know the answer immediately (too long), or we can call the simpler method
         // (in the case that it is too short)
         // ****************************************************************************************
        
         // If a string is shorter than (for type 'int', for example): 2147483647 (10 chars)
         // then we ought use the simplified method which just checks if the string is an integer.
         if (length < minArr.length) return isInteger(s);
        
         // If the string is longer than (for type 'int', for example): -2147483648 (11 chars)
         // then it cannot be an integer that fits into primitive 'int', so return false.
         if (length > (minArr.length + 1)) return false;
        
         // If the String is *EXACTLY* 11 characters long (for primitive-type 'int', for example),
         // but doesn't begin with a negative sign, we also know the answer immediately.
         if ((!negative) && (length == (minArr.length + 1))) return false;
        
         // If the String *EXACTLY* the length of MAX_NUUMBER, but it begins with a negative sign,
         // we can call the simplified method, instead as well.
         if (negative && (length == minArr.length)) return isInteger(s);
        
         // The **REST** of the code is only executed if the numeric part of the String
         // (Specifically: leaving out the '-' negative sign, which may or may not be present)
         // ... if the numeric part of the String is precisely the length of MAX_VALUE / MAX_NUMBER
         // as determined by the length of the array 'minArr'...  If the input string is
         // **PRECISELY** that length, then the string must be checked in the loop below. 
        
         int     i                       = negative ? 1 : 0;
         int     j                       = 0;
         boolean guaranteedFitIfInteger  = false;
         char    c                       = 0;
        
         while (i < length)
         {
             c = s.charAt(i);
        
             if (! guaranteedFitIfInteger)
             {
                 if (c > minArr[j]) return false;
                 if (c < minArr[j]) guaranteedFitIfInteger = true;
             }
        
             if (c < '0') return false;
             if (c > '9') return false;
        
             i++; j++;
         }
        
         // THE COMMENT BELOW DELINEATES WHAT HAPPENS FOR THE INPUT-CASE OF PRIMITIVE-TYPE 'INT'
         // (2147483648)... But it generalizes for byte, short, and long as well.
        
         // This might seem very strange.  Since the MIN_VALUE ends with an '8', but the
         // MAX_VALUE ends with a '7', and since we are checking each character to see that
         // it falls within the array above, **RATHER THAN** just returning TRUE right here,
         // we have to catch the **LONE** border/edge case where some joker actually passed the
         // String 2147483648 - which must return FALSE, since the last positive integer is
         // 2147483647 (see that it has an ending of '7', rather than an '8').
        
         return guaranteedFitIfInteger || negative || (c != minArr[minArr.length-1]);
        
      • isDouble

        🡅  🡇    
        public static boolean isDouble​(java.lang.String s)
        Tests whether an input-String can be parsed into a double, without throwing an exception.
        Returns:
        TRUE if and only if calling Double.valueOf(s) (or Double.parseDouble(s)) is guaranteed to produce a result, without throwing a NumberFormatException.

        NOTE: Whenever analyzing performance and optimizations, it is important to know just "how costly" (as an order of magnitude) a certain operation really. Constructors, for instance, that don't allocated much memory can be two orders of magnitude less costly than the JRE's costs for creating the StackTrace object when an exception (such as NumberFormatException) is thrown.

        Though it costs "extra" to check whether a String can be parsed by the Double-String Parser, if the programmer expects that exceptions will occasionally occur, the amount of time saved by checking a String before parsing it as a Double-String will actually save time - even if only 1 in 500 of those String's are invalid and would throw the exception, causing a StackTrace constructor to be invoked.
        See Also:
        FLOATING_POINT_REGEX, floatingPointPred
        Code:
        Exact Method Body:
         return floatingPointPred.test(s);
        
      • newLinesAsText

        🡅  🡇    
        public static java.lang.String newLinesAsText​(java.lang.String s)
        Converts every line-character ('\n') - and any white-space before or after that character, into the String - "\\n" - which is the actual two character sequence of a back-slash ('\'), followed by the letter 'n'.

        After new-line characters are replaced, the method will remove any duplicate spaces that are present in the String, and reduce them to a single space character
        Input StringReturned String
        "Hello World""Hello World"
        "Hello   \t   World""Hello World"
        "Hello World\n""Hello World\\n"
        "Hello   World  \n\t  \n""Hello World\\n\\n"
        "Hello Today!\nHow Are You?" "Hello Today!\\nHow Are You?"
        "Hello,\n   Testing   1,  2,  3\n" "Hello,\\nTesting 1, 2, 3\\n"
        "Hello,\n   Testing 1, 2, 3   \n\t\t\t" "Hello,\\nTesting 1, 2, 3\\n"
        "\n""\\n"
        "\n \t""\\n"
        "\n\t \n\t \n\t ""\\n\\n\\n"

        This method is used in printing Java Source Code to a terminal - in an abbreviated way! After this method is finished, java-source-as-text is actually still look readable, and can be printed in a table of methods on a page. It is used in the Java Doc Upgrader tool, and makes printing up both method-signatures and method bodies quite a bit easier.

        For a better understanding of the use and application of this function, please take a look at the 'toString' methods: Method.toString(), Constructor.toString(), Field.toString() and AnnotationElem.toString()

        FINALLY: This method uses regular-expressions, rather performing an in-place replacement using a for or while loop. It sacrifices a little efficiency for brevity. Also, the replacement used in the String.replaceAll method was tested, thouroughly. The quadruple-backslash 'n' is actually necessary! The first-escape used is to communicate with the Java-Compiler, and the second round of escaping is communicating with the Regular Expression Processor. *
        Parameters:
        s - Any java.lang.String, preferably one with multiple lines of text.
        Returns:
        A String, where each line of text has been "trimmed", and the two character sequence "\\n" inserted in-between each line.
        See Also:
        abbrevStartRDSF(String, int, boolean), abbrevEndRDSF(String, int, boolean)
        Code:
        Exact Method Body:
         return s
             .replaceAll(
                     // White-Space-Except-Newline, THEN newline, THEN White-SpaceExcept-Newline
                     "[ \t\r\f\b]*\n[ \t\r\f\b]*",
        
                     // Replace Each Occurence of that with:
                     // == COMPILES-TO ==> "\\n" == REG-EX-READS ==> BackSlash and letter 'n'
                     "\\\\n"
             )
             // == COMPILES-TO ==> "\s+" == REG-EX-READS ==> 'spaces'
             .replaceAll("\\s+", " ")
        
             // Don't forget about leading and trailing stuff...
             .trim();
        
      • abbrevStart

        🡅  🡇    
        public static java.lang.String abbrevStart​(java.lang.String s,
                                                   boolean escNewLines,
                                                   int maxLength)
        Convenience Method
        Invokes: abbrev(String, int, boolean, String, int)
        Passes: '0' to parameter 'abbrevPos', forcing the abbreviation to occur at the start of the String (if long enough to be abbreviated)
        Code:
        Exact Method Body:
         return abbrev(s, 0, escNewLines, null, maxLength);
        
      • abbrev

        🡅  🡇    
        public static java.lang.String abbrev​(java.lang.String s,
                                              int abbrevPos,
                                              boolean escapeNewLines,
                                              java.lang.String abbrevStr,
                                              int maxLength)
        This will abbreviate any String using either the ellipsis ('...'), or some other use provided abbreviation-String - as long as the provided String is longer than 'maxLength'. When 's' is, indeed, longer than 'maxLength' the returned-String will contain the ellipsis abbreviation beginning at String-index 'abbrevPos'.

        You have the option of asking that new-line characters ('\n') be escaped into the two-character String: "\\n". This optional is provided so that the output may fit on a single-line, for readability purposes. It will look somewhat like an escaped JSON file, which also substitues '\n' characters for the 'escaped' version "\\n". Note that when this occurs, the replaced-String actually only contains two characters, not three, since the first back-slash your are looking right here is, itself, an escape character!
        Parameters:
        s - This may be any Java (non-null) String
        abbrevPos - This parameter is used to indicate where the abbreviation-String should occur - if this String 's' is long enough to be abbreviated. For instance, if '0' (zero) were passed to this parameter, and 's' were longer than parameter 'maxLength', then an ellipsis would be appended to the beginning of the returned-'String'. (Or, if some other 'abbrevStr' were specified, that other abbreviation would be appended to the beginning of the returned-String)
        escapeNewLines - When this parameter is set to TRUE, any new-lines that would be included in the output String are replaced with the (two-character) "\\n" notation, instead.

        NOTE: When this parameter is passed TRUE, the output-String will have one fewer character for each '\n' (newline) that was present inside the original input-String (as long as the input-String is, indeed, being abbreviated).

        If 's' is already shorter than 'maxLength' and can fit even with the escaped-newlines, then the returned-String will be the same as the input (because it is not being abbreviated) - except that any & all new-line characters will have been escaped.
        abbrevStr - This parameter may be null, and if or when it is, it will be ignored. The default abbreviation-String is the three-dot ellipsis ('...'). When this parameter is passed a non-null value, its value will be used as the "abbreviation-String" - instead of the '...' standard-ellipsis notation.
        maxLength - This is the longest value allowed for the returned-String. When an input-String (parameter 's') is passed that is longer than the value of 'maxLength', then the String that is returned will be abbreviated to length 'maxLength'.

        NOTE: Whenever any String is passed that has a length that is less than 'maxLength', the original input-String, itself, shall be returned as the result of this function (without any ellipsis or abbreviation).
        Returns:
        If the input String has a length less-than 'maxLength', then it is returned, unchanged. If the input contained new-line characters, and you have requested to escape them, that replacement is performed first (which makes the original String} longer). Then, if the String is longer than 'maxLength', it is abbreviated, and either the default ellipsis or the user-provided 'abbrevStr' are inserted at location 'abbrevPos' and returned.

        If, after the new-line escape-replacement, the returned-String would not be longer than 'maxLength', then that escaped-String is returned, as is (without any elliptical-characters).
        Throws:
        java.lang.IllegalArgumentException - If the value for 'maxLength' is negative, or if it is less than the length of the abbreviation.

        Specifically, if 'maxLength' isn't even long enough to fit the abbreviation itself, then this exception will throw.

        If the value passed to 'abbrevPos' is negative or longer than the value passed to 'maxLength' minus the length of the ellipsis-String, then this exception will also throw.
        Code:
        Exact Method Body:
         if (maxLength < 0) throw new IllegalArgumentException
             ("The value passed to 'maxLength' " + maxLength + ", may not be zero or negative.");
        
         if (abbrevPos < 0) throw new IllegalArgumentException
             ("You have passed a negative value to parameter 'abbrevPos': " + abbrevPos);
        
         if (abbrevStr == null) abbrevStr = "...";
        
         int SLEN = s.length();
         int ALEN = abbrevStr.length();
        
         if ((abbrevPos + ALEN) >= maxLength) throw new IllegalArgumentException(
             "The value passed to parameter 'abbrevPos', " + abbrevPos + ", added to the length " +
             "of the abbreviation-ellipsis String, \"" + abbrevStr + "\", is longer than the " +
             "value provided to parameter 'maxLength' " + maxLength
         );
        
         if (! escapeNewLines) if (SLEN <= maxLength) return s;
        
         char[] cArr = new char[maxLength];
        
         // NOTE: Two lines ago, if the input string 's' actually fit, it would already have been
         //       returned (in the case that escaping new-lines was NOT requested)
         if (! escapeNewLines)
         {
             s.getChars(0, abbrevPos, cArr, 0);
             abbrevStr.getChars(0, ALEN, cArr, abbrevPos);
             s.getChars(SLEN - (maxLength - (abbrevPos + ALEN)), SLEN, cArr, abbrevPos + ALEN);
             return new String(cArr);
         }
        
         // Beginning Here: It has been determined that new-lines are to be escaped....
         int     targetPos=0, srcPos=0, oldSrcPos=0;
         char    c;
        
         while ((targetPos < abbrevPos) && (srcPos < SLEN))
        
             // When / If a new-line character is encountered, just insert the "\\n" 
             // substring.  Otherwise, normally copy the next character in the source-string
             if ((c = s.charAt(srcPos++)) == '\n')
             {
                 cArr[targetPos++] = '\\';
        
                 if ((targetPos < cArr.length) && (targetPos < abbrevPos))
                     cArr[targetPos++] = 'n';
             }
             else
                 cArr[targetPos++] = c;
        
         // This is the case where the String was short enough to fit before the
         // abbrev-pos.
         if (srcPos == SLEN) return new String(cArr, 0, targetPos);
        
         // In this loop, the iteration is done in reverse.  It starts at the end of the
         // source-String, and at the end of the out char-array, and works backward.
         // LOOP CONTINUES: Continues until the 'abbrevPos' has been reached.
         oldSrcPos   = srcPos;
         srcPos      = SLEN - 1;
         targetPos   = cArr.length - 1;
        
         while ((targetPos >= abbrevPos) && (srcPos >= oldSrcPos))
        
             // Here, we need to make sure not to over-write the 
             if ((c = s.charAt(srcPos--)) == '\n')
             {
                 cArr[targetPos--] = 'n';
        
                 if (targetPos >= abbrevPos) cArr[targetPos--] = '\\';
             }
             else
                 cArr[targetPos--] = c;
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // CASE 1: The String didn't fit into the 'maxLength' specified array, so it *DOES*
         //       need to be abbreviated.
         //       Copy the abbreviation-string into cArr, and return it.
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         if (srcPos >= oldSrcPos)
         {
             abbrevStr.getChars(0, ALEN, cArr, abbrevPos);
             return new String(cArr);
         }
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // CASE 2: The String did fit (even with escaped '\n' ==> "\\n")
         //         **AND** It fit PRECISELY-EXACTLY into the output char-array
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         if ((targetPos == (abbrevPos-1)) && (srcPos == (oldSrcPos-1)))
             return new String(cArr);
        
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
         // CASE 3: There is extra-room in the output-String
         //         This means that the copy which just occurred in the previous loop was wrong
         //         There isn't an easy way to avoid this (other than counting new-lines first)
         //         Instead, shift the char-array, and then return it
         // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        
         srcPos = targetPos + 1;
         targetPos = abbrevPos;
         while (srcPos < cArr.length) cArr[targetPos++] = cArr[srcPos++];
        
         return new String(cArr, 0, targetPos);
        
      • abbrevEnd

        🡅  🡇    
        public static java.lang.String abbrevEnd​(java.lang.String s,
                                                 boolean escapeNewLines,
                                                 int maxLength)
        Convenience Method
        Invokes: abbrev(String, boolean, boolean, String, int)
        Parameter: spaceBeforeAbbrev set to FALSE
        Abbreviates: Default ellipsis ('...') are placed at the end of the String
        Code:
        Exact Method Body:
         return abbrev(s, false, escapeNewLines, null, maxLength);
        
      • abbrev

        🡅  🡇    
        public static java.lang.String abbrev​(java.lang.String s,
                                              boolean spaceBeforeAbbrev,
                                              boolean escapeNewLines,
                                              java.lang.String abbrevStr,
                                              int maxLength)
        This will abbreviate any String using either the ellipsis ('...'), or some other use provided abbreviation-String, if the provided String is longer than 'maxLength'. If the returned-String is, indeed, abbreviated then the elliptical-abbreviation String will be placed at the end of the returned-String

        You have the option of asking that new-line characters ('\n') be escaped into the two-character String: "\\n". This optional is provided so that the output may fit on a single-line, for readability purposes. It will look somewhat like an escaped JSON file, which also substitues '\n' characters for the 'escaped' version "\\n". Note that when this occurs, the replaced-String actually only contains two characters, not three, since the first back-slash your are looking right here is, itself, an escape character!
        Parameters:
        s - This may be any Java (non-null) String
        spaceBeforeAbbrev - This ensures that for whatever variant of ellipsis being used, the space-character is inserted directly before appending the ellipsis "..." or the user-provided 'abbrevStr'.
        escapeNewLines - When this parameter is set to TRUE, any new-lines that would be included in the output String are replaced with the (two-character) "\\n" notation, instead.

        NOTE: When this parameter is passed TRUE, the output-String will have one fewer character for each '\n' (newline) that was present inside the original input-String (as long as the input-String is, indeed, being abbreviated).

        If 's' is already shorter than 'maxLength' and can fit even with the escaped-newlines, then the returned-String will be the same as the input (because it is not being abbreviated) - except that any & all new-line characters will have been escaped.
        abbrevStr - This parameter may be null, and if or when it is, it will be ignored. The default abbreviation-String is the three-dot ellipsis ('...'). When this parameter is passed a non-null value, its value will be used as the "abbreviation-String" - instead of the '...' standard-ellipsis notation.
        maxLength - This is the longest value allowed for the returned-String. When an input-String (parameter 's') is passed that is longer than the value of 'maxLength', then the String that is returned will be abbreviated to length 'maxLength'.

        NOTE: Whenever any String is passed that has a length that is less than 'maxLength', the original input-String, itself, shall be returned as the result of this function (without any ellipsis or abbreviation).
        Returns:
        If the input String has a length less-than 'maxLength', then it is returned, unchanged. If the input contained new-line characters, and you have requested to escape them, that replacement is performed first (which makes the original String} longer). Then, if the String is longer than 'maxLength', it is abbreviated, and either the default ellipsis or the user-provided 'abbrevStr' are are appended to the end and returned.
        Throws:
        java.lang.IllegalArgumentException - If the value for 'maxLength' is negative, or if it is less than the length of the abbreviation plus the value of 'spaceBeforeAbbrev'.

        Specifically, if 'maxLength' isn't even long enough to fit the abbreviation itself, then this exception will throw.
        Code:
        Exact Method Body:
         if (maxLength < 0) throw new IllegalArgumentException
             ("The value passed to 'maxLength' " + maxLength + ", may not be zero or negative.");
        
         // If the original String is shorter than the 'maxLength' parameter, return the original
         // String immediately - **UNLESS** the user has requested to replace new-line characters
         // with the "Escaped New-Line Sequence "\\n"
         if (! escapeNewLines) if (s.length() <= maxLength) return s;
        
         // The default abbreviation is just the ellipsis.
         if (abbrevStr == null) abbrevStr = "...";
        
         char[]  cArr        = new char[maxLength];
         int     srcPos      = 0;
         int     targetPos   = 0;
         char    c           = 0;
         int     LEN         = s.length();
         int     END         = maxLength - abbrevStr.length() - (spaceBeforeAbbrev ? 1 : 0);
        
         if (END < 0) throw new IllegalArgumentException(
             "The value provided to 'maxLength' was : " + maxLength + ", but this isn't long " +
             "enough to even contain the abbreviation-string: \"" + (spaceBeforeAbbrev ? " " : "") +
             abbrevStr + "\""
         );
        
         if (! escapeNewLines)
             // NOTE: Here, the abbreviation will be necessary, so use 'END' instead of 'LEN'
             //       This is because at the top, if the whole-String fit, this method would have
             //       already returned ... if (! escapeNewLines) *above*
             // ALSO: More efficient at copying String-arrays than a 'for-loop' is 'getChars'
             s.getChars(0, targetPos = END, cArr, 0);
         else
         {
             while ((targetPos < maxLength) && (srcPos < LEN))
        
                 // When / If a new-line character is encountered, just insert the "\\n" 
                 // substring.  Otherwise, normally copy the next character in the source-string
                 if ((c = s.charAt(srcPos++)) == '\n')
                 {
                     cArr[targetPos++] = '\\';
                     if (targetPos < cArr.length) cArr[targetPos++] = 'n';
                 }
                 else
                     cArr[targetPos++] = c;
        
             // If every single character from the input String has been appended to the output,
             // then there is no need to add the abbreviation String (usually, the ellipsis '...').
             // In this case, just return original-String immediately (with the escaped newlines).
             if (srcPos == LEN)
                 return new String(cArr, 0, targetPos);
        
             targetPos -= (abbrevStr.length() + (spaceBeforeAbbrev ? 1 : 0));
         }
        
         // NOTE: There is a (false) special-case, where there *ALREADY* IS a space before the
         //       addition of the "ellipsis" - so it *MIGHT SEEM* you wouldn't want to add another
         //       a second-space, unfortunately, if they have asked for a space before the
         //       abbreviation-ellipsis, it is also inappropriate to add another character from the
         //       original String.
        
         // LONG-STORY-SHORT: There is a (small) chance that there will be two spaces in a row here,
         //                   but in order to comply with the 'maxLength' parameter, there is no
         //                   alternative.
         if (spaceBeforeAbbrev) cArr[targetPos++] = ' ';
        
         abbrevStr.getChars(0, abbrevStr.length(), cArr, targetPos);
         return new String(cArr, 0, targetPos + abbrevStr.length());
        
      • isJavaTypeStr

        🡅    
        public static boolean isJavaTypeStr​(java.lang.String s)
        Checks whether an input String is a valid Type Identifier. Type Identifiers are the names of Java Classes, Interfaces, Enumerated-Types, Annotations and Records. The two methods Character.isJavaIdentifier.start(char) and Characters.isJavaIdentifer.part(char) are utilized here to produce this method's return value. Below is a table of several output-results (table's second column) that would be returned by the specified inputs String's (first column).

        Function InputReturn Value
        Stringtrue
        Map.Entrytrue
        Vectortrue
        Vector<String>false
        Map.Entry<String, Integer>false
        String.indexOf(1)false
        String.indexOftrue
        MyOuterClass.MyInnerClass03true
        MyOuterClass.03MyInnerClassfalse


        The only real check being performed is whether the String is a valid 'Java Identifier' - or, if a period '.' is present - that it is a list of Java Identifier's which are all separated by a single period character. This is done to ensure that String's which reference Java Inner Classes, Interfaces, Enumerations, etc. also produce a TRUE return value.
        Parameters:
        s - Any Java String.
        Returns:
        TRUE if and only if the Java Compiler could interpret 's' as a valid reference to a Java Type. In computer-programming, the world Type can have a lot of meanings, but here, the word should be interpreted as a Java Class, Interface, Enumeration (an 'enum'), Annotation or Record.

        NOTE: 's' may include the period '.' since inner classes, enum's and interfaces are also valid Java Type's. Two consecutive period-characters, or a period at the beginning or ending of 's' will result in this method returning FALSE.
        Code:
        Exact Method Body:
         if (s.length() == 0) return false;
        
         // Java restricts the first character of a java-identifier to a smaller subset than the
         // other characters in an identifier.  Use method 'isJavaIdentifierStart'
        
         if (! Character.isJavaIdentifierStart(s.charAt(0))) return false;
        
         int     len = s.length();
         char    c   = 0;
        
         for (int i=1; i < len; i++)
        
             if (! Character.isJavaIdentifierPart(c = s.charAt(i)))
             {
                 if (c == '.')
                 {
                     // A second (subsequent) period-character (in a row) ==> FALSE
                     if (s.charAt(i-1) == '.') return false;
        
                     // The LAST character in the String is a period-character ==> FALSE
                     if (i == (len-1)) return false;
        
                     // The character immediately following a period isn't a valid Java Identifier
                     // Start ==> FALSE
        
                     if (! Character.isJavaIdentifierStart(s.charAt(++i))) return false;
                 }
                 else
                     // Character is NEITHER a period, NOR a Java Identifier Part ==> FALSE
                     return false;
             }
        
         // All metrics / tests have succeeded (which would have resulted in immediate exiting of
         // this method, and a FALSE return value) ... therefore return TRUE.
         return true;