package Torello.Java;

import java.util.*;
import java.util.regex.*;
import java.io.*;
import java.util.stream.*;
import java.util.function.*;

import java.text.DecimalFormat;
import java.net.URL;

import Torello.JavaDoc.IntoHTMLTable;
import Torello.JavaDoc.LinkJavaSource;

import static Torello.JavaDoc.Entity.FIELD;
import static Torello.JavaDoc.IntoHTMLTable.Background.BlueDither;
import static Torello.JavaDoc.IntoHTMLTable.Background.GreenDither;

/**
 * A plethora of extensions to Java's {@code String} class.
 * <EMBED CLASS='external-html' DATA-FILE-ID=STRING_PARSE>
 */
@Torello.JavaDoc.StaticFunctional
public class StringParse
{
    private StringParse() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constants
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This regular expression simply matches white-space found in a java {@code String}.
     * @see #removeWhiteSpace(String)
     */
    public static final Pattern WHITE_SPACE_REGEX = Pattern.compile("\\s+");

    /**
     * This {@code Predicate<String>} checks whether the contents of a {@code java.lang.String}
     * are comprised of only White-Space Characters.
     * 
     * <BR /><BR />Java's {@code 'asMatchPredicate'} is very similar to appending the Reg-Ex
     * Control-Characters {@code '^'} and {@code '$'} to the beginning and ending of a
     * {@code String}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Important:</B> Since the Regular Expression used is the
     * one defined, above, as {@code \w+} - <I>using the {@code '+'}, rather than the
     * {@code '*'}</I> - this {@code Predicate} will return {@code FALSE} when a Zero-Length
     * {@code String} is passed as input.
     * 
     * @see #WHITE_SPACE_REGEX
     * @see #onlyWhiteSpace_OrZeroLen
     */
    public static final Predicate<String> onlyWhiteSpace =
        WHITE_SPACE_REGEX.asMatchPredicate();

    /**
     * This is a {@code Predicate} that works in an identical manner to {@link #onlyWhiteSpace},
     * with the minor addded stipulation that a Zero-Length {@code String} will generate a 
     * {@code TRUE} / pass result from the {@code Predicate.test(String)} method.
     * 
     * @see #onlyWhiteSpace
     */
    public static final Predicate<String> onlyWhiteSpace_OrZeroLen =
        Pattern.compile("^\\s*$").asPredicate();

    /**
     * This regular expression simply matches the comma.  The only reason for including this here
     * is because the java {@code class 'Pattern'} contains a method called
     * {@code Stream<String> 'splitAsStream(CharSequence)'} which is used for the CSV method
     * further below
     * 
     * @see StrCSV#CSV(String, boolean, boolean)
     * @see FileRW#readDoublesFromFile(String, boolean, boolean)
     * @see FileRW#readLongsFromFile(String, boolean, boolean, int)
     */
    public static final Pattern COMMA_REGEX = Pattern.compile(",");

    /**
     * This regular expression is used for integer and floating-point numbers that use the
     * comma ({@code ','}) between the digits that comprise the number.  For example, this
     * Regular Expression would match the {@code String} {@code "900,800,75.00"}.
     * 
     * @see FileRW#readIntsFromFile(String, boolean, boolean, int)
     */
    public static final Pattern NUMBER_COMMMA_REGEX = Pattern.compile("(\\d),(\\d)");

    /**
     * This represents any version of the new-line character.  Note that the {@code '\r\n'} version
     * comes before the single {@code '\r'} version in the regular-expression, to guarantee that
     * if both are present, they are treated as a single newline.
     */
    public static final Pattern NEWLINEP = Pattern.compile("\\r\\n|\\r|\\n");

    /**
     * Predicate for new-line characters
     * @see #NEWLINEP
     */
    public static final Predicate<String> newLinePred = NEWLINEP.asPredicate();

    /** This is the list of characters that need to be escaped for a regular expression */
    public static final String REG_EX_ESCAPE_CHARS = "\\/()[]{}$^+*?-.";

    /** Alpha-Numeric RegEx */
    public static final Pattern ALPHA_NUMERIC = Pattern.compile("^[\\d\\w]*$");

    /**
     * Alpha-Numeric {@code String} Predicate.
     * @see #ALPHA_NUMERIC
     */
    public static final Predicate<String> alphaNumPred = ALPHA_NUMERIC.asPredicate();

    /** An empty {@code String} array. */
    public static final String[] EMPTY_STR_ARRAY = {};


    // ********************************************************************************************
    // ********************************************************************************************
    // methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Trims any white-space {@code Characters} from the end of a {@code String}.
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR><TH>Input String:</TH><TH>Output String:</TH></TR>
     * <TR><TD>{@code "A Quick Brown Fox\n \t"}</TD><TD>{@code "A Quick Brown Fox"}</TD></TR>
     * <TR><TD>{@code "\tA Lazy Dog."}</TD><TD>{@code "\tA Lazy Dog."}</TD></TR>
     * <TR><TD>{@code "   "  (only white-space)}</TD><TD>{@code ""}</TD></TR>
     * <TR><TD>{@code "" (empty-string)}</TD><TD>{@code ""}</TD></TR>
     * <TR><TD>{@code null}</TD><TD>throws {@code NullPointerException}</TD></TR>
     * </TABLE>
     * 
     * @param s Any Java {@code String}
     * 
     * @return A copy of the same {@code String} - <I>but all characters that matched Java
     * method {@code java.lang.Character.isWhitespace(char)}</I> and were at the end of the 
     * {@code String} will not be included in the returned {@code String}.
     * 
     * <BR /><BR />If the {@code zero-length String} is passed to parameter {@code 's'}, it
     * shall be returned immediately.
     * 
     * <BR /><BR />If the resultant-{@code String} has zero-length, it is returned, without
     * exception.
     */
    public static String trimRight(String s)
    {
        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);
    }

    /**
     * Trims any white-space {@code Characters} from the beginning of a {@code String}.
     * 
     * <TABLE CLASS=JDBriefTable>
     * <TR><TH>Input String:</TH><TH>Output String:</TH></TR>
     * <TR><TD>{@code "\t  A Quick Brown Fox"}</TD><TD>{@code "A Quick Brown Fox"}</TD></TR>
     * <TR><TD>{@code "A Lazy Dog. \n\r\t"}</TD><TD>{@code "A Lazy Dog. \n\r\t"}</TD></TR>
     * <TR><TD>{@code "   "  (only white-space)}</TD><TD>{@code ""}</TD></TR>
     * <TR><TD>{@code ""  (empty-string)}</TD><TD>{@code ""}</TD></TR>
     * <TR><TD>{@code null}</TD><TD>throws {@code NullPointerException}</TD></TR>
     * </TABLE>
     * 
     * @param s Any Java {@code String}
     * 
     * @return A copy of the same {@code String} - <I>but all characters that matched Java
     * method {@code java.lang.Character.isWhitespace(char)}</I> and were at the start of the 
     * {@code String} will not be included in the returned {@code String}.
     * 
     * <BR /><BR />If the {@code zero-length String} is passed to parameter {@code 's'}, it
     * shall be returned immediately.
     * 
     * <BR /><BR />If the resultant-{@code String} has zero-length, it is returned, without
     * exception.
     */
    public static String trimLeft(String s)
    {
        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);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_SPC_PAD_L_DESC>
     * @param s This may be any {@code java.lang.String}
     * @param totalStringLength
     * <EMBED CLASS='external-html' DATA-PREPOST=pre DATA-FILE-ID=STRP_SPC_PAD_TOTAL_LEN>
     * @throws IllegalArgumentException If {@code totalStringLength} is zero or negative.
     * @see #rightSpacePad(String, int)
     */
    public static String leftSpacePad(String s, int totalStringLength)
    {
        CHECK_NEGATIVE(totalStringLength);

        return (s.length() >= totalStringLength) 
            ? s 
            : String.format("%1$" + totalStringLength + "s", s);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_SPC_PAD_R_DESC>
     * @param s This may be any {@code java.lang.String}
     * @param totalStringLength
     * <EMBED CLASS='external-html' DATA-PREPOST=post DATA-FILE-ID=STRP_SPC_PAD_TOTAL_LEN>
     * @throws IllegalArgumentException If {@code totalStringLength} is zero or negative.
     * @see #leftSpacePad(String, int)
     */
    public static String rightSpacePad(String s, int totalStringLength)
    {
        CHECK_NEGATIVE(totalStringLength);

        return (s.length() >= totalStringLength) 
            ? s 
            : String.format("%1$-" + totalStringLength + "s", s);
    }

    private static void CHECK_NEGATIVE(int totalStringLength)
    {
        if (totalStringLength <= 0) throw new IllegalArgumentException(
            "totalString length was '" + totalStringLength + ", " +
            "however it is expected to be a positive integer."
        );
    }

    /**
     * Runs a Regular-Expression over a {@code String} to retrieve all matches that occur between
     * input {@code String} parameter {@code 's'} and Regular-Expression {@code 'regEx'}.
     * 
     * @param s Any Java {@code String}
     * @param regEx Any Java Regular-Expression
     * 
     * @param eliminateOverlappingMatches When this parameter is passed {@code 'TRUE'}, successive
     * matches that have portions which overlap each-other are eliminated.
     * 
     * @return An array of all {@code MatchResult's} (from package {@code 'java.util.regex.*'}) that
     * were produced by iterating the {@code Matcher's} {@code 'find()'} method.
     */
    public static MatchResult[] getAllMatches
        (String s, Pattern regEx, boolean eliminateOverlappingMatches)
    {
        Stream.Builder<MatchResult> b       = Stream.builder();
        Matcher                     m       = regEx.matcher(s);
        int                         prevEnd = 0;

        while (m.find())
        {
            MatchResult matchResult = m.toMatchResult();

            // This skip any / all overlapping matches - if the user has requested it
            if (eliminateOverlappingMatches) if (matchResult.start() < prevEnd) continue;

            b.accept(matchResult);

            prevEnd = matchResult.end();
        }

        // Convert the Java-Stream into a Java-Array and return the result
        return b.build().toArray(MatchResult[]::new);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Helper set & get for strings
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This sets a character in a {@code String} to a new value, and returns a result
     * @param str Any java {@code String}
     * @param i An index into the underlying character array of that {@code String}.
     * @param c A new character to be placed at the <I>i'th position</I> of this {@code String}.
     * 
     * @return a new java {@code String}, with the appropriate index into the {@code String}
     * substituted using character parameter {@code 'c'}.
     */
    public static String setChar(String str, int i, char c)
    {
        return ((i + 1) < str.length())
            ? (str.substring(0, i) + c + str.substring(i + 1))
            : (str.substring(0, i) + c);
    }

    /**
     * This removes a character from a {@code String}, and returns a new {@code String} as a
     * result.
     * 
     * @param str Any Java-{@code String}.
     * 
     * @param i This is the index into the underlying java {@code char}-array whose character will
     * be removed from the return {@code String}.
     * 
     * @return Since Java {@code String}'s are all immutable, this {@code String} that is returned
     * is completely new, with the character that was originally at index 'i' removed.
     */
    public static String delChar(String str, int i)
    {
        if ((i + 1) < str.length())
            return str.substring(0, i) + str.substring(i + 1);
        else
            return str.substring(0, i);
    }

    /**
     * Returns the same {@code String} is input, but trims all spaces down to a single space.
     * Each and every <I>lone / independent or contiguous</I> white-space character is reduced
     * to a single space-character.
     * 
     * <TABLE CLASS=JDBriefTable>
     * <TR><TH>Input String</TH><TH>Output String</TH></TR>
     * <TR><TD><PRE>{@code "This   has   extra   spaces\n"}</PRE></TD>
     *     <TD>{@code "This has extra spaces "}</TD>
     * </TR>
     * <TR><TD>{@code "This does not"}</TD>
     *     <TD>{@code "This does not"}</TD>
     * </TR>
     * <TR><TD>{@code "\tThis\nhas\ttabs\nand\tnewlines\n"}</TD>
     *     <TD>{@code " This has tabs and newlines "}</TD>
     * </TR>
     * </TABLE>
     *
     * @param s Any Java {@code String}
     * 
     * @return A {@code String} where all white-space is compacted to a single space.  This is
     * generally how HTML works, when it is displayed in a browser.
     */
    public static String removeDuplicateSpaces(String s)
    { return StringParse.WHITE_SPACE_REGEX.matcher(s).replaceAll(" "); }

    /**
     * This string-modify method simply removes any and all white-space matches found within a
     * java-{@code String}.
     * 
     * <TABLE CLASS=JDBriefTable>
     * <TR><TH>Input String</TH><TH>Output String</TH></TR>
     * <TR><TD><PRE>{@code "This   Has   Extra   Spaces\n"}</PRE></TD>
     *     <TD>{@code "ThisHasExtraSpaces"}</TD>
     * </TR>
     * <TR><TD>{@code "This Does Not"}</TD>
     *     <TD>{@code "ThisDoesNot"}</TD>
     * </TR>
     * <TR><TD>{@code "\tThis\nHas\tTabs\nAnd\tNewlines\n"}</TD>
     *     <TD>{@code "ThisHasTabsAndNewlines"}</TD>
     * </TR>
     * </TABLE>
     * 
     * @param s Any {@code String}, but if it has any white-space (space that matches
     * regular-expression: {@code \w+}) then those character-blocks will be removed
     * 
     * @return A new {@code String} without any {@code \w} (RegEx for 'whitespace')
     * 
     * @see #WHITE_SPACE_REGEX
     */
    public static String removeWhiteSpace(String s)
    { return WHITE_SPACE_REGEX.matcher(s).replaceAll(""); }

    /**
     * Generates a {@code String} that contains {@code n} copies of character {@code c}.
     * @return {@code n} copies of {@code c}, as a {@code String}.
     * @throws IllegalArgumentException If the value passed to parameter {@code 'n'} is negative
     * @see StrSource#caretBeneath(String, int)
     */
    public static String nChars(char c, int n)
    {
        if (n < 0) throw new IllegalArgumentException("Value of parameter 'n' is negative: " + n);

        char[] cArr = new char[n];
        Arrays.fill(cArr, c);
        return new String(cArr);
    }

    /**
     * Generates a {@code String} that contains {@code n} copies of {@code s}.
     * @return {@code n} copies of {@code s} as a {@code String}.
     * @throws NException if the value provided to parameter {@code 'n'} is negative.
     */
    public static String nStrings(String s, int n)
    {
        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();
    }

    /**
     * This method checks whether or not a java-{@code String} has white-space.
     * 
     * @param s Any Java-{@code String}.  If this {@code String} has any white-space, this method
     * will return {@code TRUE}
     * 
     * @return {@code TRUE} If there is any white-space in this method, and {@code FALSE} otherwise.
     * 
     * @see #WHITE_SPACE_REGEX
     */
    public static boolean hasWhiteSpace(String s)
    { return WHITE_SPACE_REGEX.matcher(s).find(); }

    /**
     * Counts the number of instances of character input {@code char c} contained by the
     * input {@code String s}
     * 
     * @param s Any {@code String} containing any combination of ASCII/UniCode characters
     * 
     * @param c Any ASCII/UniCode character.
     * 
     * @return The number of times {@code char c} occurs in {@code String s}
     */
    public static int countCharacters(String s, char c)
    {
        int count = 0;
        int pos   = 0;
        while ((pos = s.indexOf(c, pos + 1)) != -1) count++;
        return count;
    }


    /**
     * If the {@code String} passed to this method contains a single-quote on both sides of the
     * {@code String}, or if it contains a double-quote on both sides of this {@code String}, then
     * this method shall return a new {@code String} that is shorter in length by 2, and leaves off
     * the first and last characters of the input parameter {@code String}.
     * 
     * <BR /><BR /><B>HOPEFULLY,</B> The name of this method explains clearly what this method does
     *
     * @param s This may be any java {@code String}.  Only {@code String's} whose first and last
     * characters are not only quotation marks (single or double), but also they are <B>the same,
     * identical, quotation marks on each side.</B>
     * 
     * @return A new {@code String} that whose first and last quotation marks are gone - if they
     * were there when this method began.
     */
    public static String ifQuotesStripQuotes(String s)
    {
        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;
    }

    /**
     * Counts the number of lines of text inside of a Java {@code String}.
     * 
     * @param text This may be any text, as a {@code String}.
     * 
     * @return Returns the number of lines of text.  The integer returned shall be precisely
     * equal to the number of {@code '\n'} characters <B><I>plus one!</I></B>
     */
    public static int numLines(String text)
    {
        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;
    }



    // ********************************************************************************************
    // ********************************************************************************************
    // Find / Front Last-Front-Slash
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This function finds the position of the last "front-slash" character {@code '/'} in a
     * java-{@code String}
     * 
     * @param urlOrDir This is any java-{@code String}, but preferably one that is a
     * {@code URL}, or directory.
     * 
     * @return The {@code String}-index of the last 'front-slash' {@code '/'} position in a
     * {@code String}, or {@code -1} if there are not front-slashes.
     */
    public static int findLastFrontSlashPos(String urlOrDir)
    { return urlOrDir.lastIndexOf('/'); }

    /**
     * This returns the contents of a {@code String}, after the last front-slash found.
     * 
     * <BR /><BR /><B>NOTE:</B> If not front-slash {@code '/'} character is found, then the
     * original {@code String} is returned.
     *
     * @param urlOrDir This is any java-{@code String}, but preferably one that is a
     * {@code URL}, or directory.
     * 
     * @return the portion of the {@code String} after the final front-slash {@code '/'} character.
     * If there are no front-slash characters found in this {@code String}, then the original
     * {@code String} shall be returned.
     */
    public static String fromLastFrontSlashPos(String urlOrDir)
    {
        int pos = urlOrDir.lastIndexOf('/');
        if (pos == -1) return urlOrDir;
        return urlOrDir.substring(pos + 1);
    }

    /**
     * This returns the contents of a {@code String}, before the last front-slash found (including
     * the front-slash {@code '/'} itself).
     * 
     * <BR /><BR /><B>NOTE:</B> If no front-slash {@code '/'} character is found, then null is
     * returned.
     *
     * @param urlOrDir This is any java-{@code String}, but preferably one that is a
     * {@code URL}, or directory.
     * 
     * @return the portion of the {@code String} <I><B>before and including</B></I> the final
     * front-slash {@code '/'} character.  If there are no front-slash characters found in this 
     * {@code String}, then null.
     */
    public static String beforeLastFrontSlashPos(String urlOrDir)
    {
        int pos = urlOrDir.lastIndexOf('/');
        if (pos == -1) return null;
        return urlOrDir.substring(0, pos + 1);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Find / From Last-File-Separator
    // ********************************************************************************************
    // ********************************************************************************************


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

    /**
     * This returns the contents of a {@code String}, after the last
     * {@code 'java.io.File.separator'} found. 
     * 
     * <BR /><BR /><B>NOTE:</B> If no {@code 'java.io.File.separator'} character is found, then
     * the original {@code String} is returned.
     *
     * @param fileOrDir This is any java-{@code String}, but preferably one that is a filename or
     * directory-name
     * 
     * @return the portion of the {@code String} after the final  {@code 'java.io.File.separator'}
     * character.  If there are no such characters found, then the original {@code String} shall
     * be returned.
     */
    public static String fromLastFileSeparatorPos(String fileOrDir)
    {
        int pos = fileOrDir.lastIndexOf(File.separator.charAt(0));
        if (pos == -1) return fileOrDir;
        return fileOrDir.substring(pos + 1);
    }

    /**
     * This returns the contents of a {@code String}, before the last
     * {@code 'java.io.File.separator'} (including the separator itself).
     * 
     * <BR /><BR /><B>NOTE:</B> If no {@code 'java.io.File.separator'} character is found,
     * then null is returned.
     *
     * @param urlOrDir This is any java-{@code String}, but preferably one that is a
     * {@code URL}, or directory.
     * 
     * @return the portion of the {@code String} <I><B>before and including</B></I> the final
     * {@code 'java.io.File.separator'} character.  If there are no such characters found in this 
     * {@code String}, then null is returned.
     */
    public static String beforeLastFileSeparatorPos(String urlOrDir)
    {
        int pos = urlOrDir.lastIndexOf(File.separator.charAt(0));
        if (pos == -1) return null;
        return urlOrDir.substring(0, pos + 1);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Find / From File-Extension
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method swaps the ending 'File Extension' with another, parameter-provided, extension.
     * @param fileNameOrURLWithExtension Any file-name (or {@code URL}) that has an extension.
     * @param newExtension <EMBED CLASS='external-html' DATA-FILE-ID=STRP_SWAP_EXT_NEWEX>
     * @return The new file-name or {@code URL} having the substituted extension.
     * @throws StringFormatException 
     */
    public static String swapExtension(String fileNameOrURLWithExtension, String newExtension)
    {
        final 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;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_REM_EXT_DESC>
     * @param fileNameOrURL Any file-name or {@code URL}, as a {@code String}.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_REM_EXT_RET>
     */
    public static String removeExtension(String fileNameOrURL)
    {
        final int dotPos = fileNameOrURL.lastIndexOf('.');

        return (dotPos == -1)
            ? fileNameOrURL
            : fileNameOrURL.substring(0, dotPos);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FIND_EXT_DESC>
     * @param file This may be any Java-{@code String}, but preferably one that represents a file.
     * @param includeDot <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FIND_EXT_INCL>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FIND_EXT_RET>
     */
    public static int findExtension(String file, boolean includeDot)
    {
        int pos = file.lastIndexOf('.');

        if (pos == -1)                  return -1;
        else if (includeDot)            return pos;
        else if (++pos < file.length()) return pos;
        else                            return -1;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FROM_EXT_DESC>
     * @param file This is any java-{@code String}, but preferably one that is a filename.
     * 
     * @param includeDot Indicates whether the period {@code '.'} is to be included in the
     * returned-{@code String}.
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FROM_EXT_RET>
     */
    public static String fromExtension(String file, boolean includeDot)
    {
        final int pos = findExtension(file, includeDot);

        return (pos == -1)
            ? null
            : file.substring(pos);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_BEFORE_EXT_DESC>
     * @param file This is any java-{@code String}, but preferably one that is a filename.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_BEFORE_EXT_RET>
     */
    public static String beforeExtension(String file)
    {
        final int pos = file.lastIndexOf('.');

        return (pos == -1)
            ? file
            : file.substring(0, pos);
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_BEFORE_EXT_DESC>
     * @param url A URL as a {@code String} - like {@code http://domain/directory/[file]}
     * @return substring(0, index of last front-slash ({@code '/'}) in {@code String})
     */
    public static String findURLRoot(String url)
    {
        final int pos = findLastFrontSlashPos(url);

        return (pos == -1)
            ? null
            : url.substring(0, pos + 1);
    }

    /**
     * String text that is situated before the first white-space character in the string.
     * @return After breaking the {@code String} by white-space, this returns the first 'chunk'
     * before the first whitespace.
     */
    public static String firstWord(String s)
    {
        final int pos = s.indexOf(" ");

        return (pos == -1)
            ? s
            :  s.substring(0, pos);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Removing parts of a string
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This function will remove any pairs of Brackets within a {@code String}, and returned the
     * paired down {@code String}
     * 
     * @param s <EMBED CLASS='external-html' DATA-FILE-ID=STRP_RMV_BRACKETS_S>
     * @return The same {@code String}, but with any bracket-pairs removed.
     */
    public static String removeBrackets(String s) { return remove_(s, '[', ']'); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_RMV_BRACES_DESC>
     * @param s <EMBED CLASS='external-html' DATA-FILE-ID=STRP_RMV_BRACES_S>
     * @return The same {@code String}, but with any curly-brace-pairs removed.
     */
    public static String removeBraces(String s) { return remove_(s, '{', '}'); }

    /**
     * Removes Parenthesis, similar to other parenthetical removing functions.
     * @param s <EMBED CLASS='external-html' DATA-FILE-ID=STRP_RMV_PARENS_S>
     * @return The same {@code String}, but with any parenthesis removed.
     */
    public static String removeParens(String s) { return remove_(s, '(', ')'); }

    /**
     * Removes all parenthetical notations.  Calls all <I><B>remove functions</B></I>
     * @param s Any valid string
     * @return The same string, but with all parenthesis, curly-brace &amp; bracket pairs removed.
     * @see #removeParens(String)
     * @see #removeBraces(String)
     * @see #removeBrackets(String)
     */
    public static String removeAllParenthetical(String s)
    { return removeParens(removeBraces(removeBrackets(s))); }
    
    private static String remove_(String s, char left, char right)
    {
        int p = s.indexOf(left);
        if (p == -1) return s;

        String ret = s.substring(0, p).trim();

        for (++p; (s.charAt(p) != right) && (p < s.length()); p++);

        if (p >= (s.length() - 1)) return ret;

        ret += " " + s.substring(p + 1).trim();

        if (ret.indexOf(left) != -1)    return remove_(ret.trim(), left, right);
        else                            return ret.trim();
    }



    // ********************************************************************************************
    // ********************************************************************************************
    // Base-64 Encoded Java Objects
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_OBJ_2_B64_STR_DESC>
     * @param o Any java {@code java.lang.Object}.  This object must be Serializable, or throws.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_OBJ_2_B64_STR_RET>
     * @see #b64StrToObj(String)
     */
    @LinkJavaSource(handle="B64", name="objToB64Str")
    public static String objToB64Str(Object o) throws IOException
    { return B64.objToB64Str(o); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_B64_STR_2_OBJ_DESC>
     * @param str <EMBED CLASS='external-html' DATA-FILE-ID=STRP_B64_STR_2_OBJ_STR>
     * @return A de-compressed {@code java.lang.Object} converted back from a B64-{@code String}
     * @see #objToB64Str(Object)
     */
    @LinkJavaSource(handle="B64", name="b64StrToObj")
    public static Object b64StrToObj(String str) throws IOException
    { return B64.b64StrToObj(str); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_O_2_B64_MSTR_DESC>
     * @param o <EMBED CLASS='external-html' DATA-FILE-ID=STRP_O_2_B64_MSTR_O>
     * @return A Base-64 MIME-Encoded {@code String} of any serializable {@code java.lang.Object}
     * @see #objToB64Str(Object)
     * @see #b64MimeStrToObj(String)
     */
    @LinkJavaSource(handle="B64", name="objToB64MimeStr")
    public static String objToB64MimeStr(Object o) throws IOException
    { return B64.objToB64MimeStr(o); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_B64_MSTR_2_O_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=STRP_B64_MSTR_2_O_RET>
     * @see #b64StrToObj(String)
     * @see #objToB64MimeStr(Object)
     */
    @LinkJavaSource(handle="B64", name="b64MimeStrToObj")
    public static Object b64MimeStrToObj(String str) throws IOException
    { return B64.b64MimeStrToObj(str); }


    // ********************************************************************************************
    // ********************************************************************************************
    // '../' (Parent Directory)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Computes a "relative {@code URL String}".
     * @param fileName This is a fileName whose ancestor directory needs to be <I>relative-ized</I>
     * @param ancestorDirectory This is an ancestor (container) directory.
     * @param separator The separator character used to separate file-system directory names.
     * @return                          <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_RET>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_IAEX>
     */
    @LinkJavaSource(handle="DotDots", name="specifiedAncestor")
    public static String dotDots(String fileName, String ancestorDirectory, char separator)
    { return DotDots.specifiedAncestor(fileName, ancestorDirectory, separator); }


    /**
     * <BR>See Docs: Method {@link #dotDotParentDirectory(String, char, short)}
     * <BR>Converts: Input {@code URL} to a {@code String} - eliminates non-essential 
     * {@code URI}-information (Such as: {@code Query-Strings, and others as well})
     * <BR>Passes: Character {@code char '/'}, the separator character used in {@code URL's}
     * <BR>Passes: A {@code '1'} to parameter {@code 'nLevels'} - only going up one directory
     */
    @IntoHTMLTable(background=BlueDither, title="Rerieve the Parent-Directory of a URL")
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(URL url)
    {
        final String urlStr = url.getProtocol() + "://" + url.getHost() + url.getPath();
        return DotDots.parentDir(urlStr, '/', (short) 1);
    }


    /**
     * <BR>See Docs: Method {@link #dotDotParentDirectory(String, char, short)}
     * <BR>Passes: {@code char '/'}, the separator character used in {@code URL's}
     * <BR>Passes: {@code '1'} to parameter {@code 'nLevels'} - only going up on directory
     */
    @IntoHTMLTable(
        background=GreenDither,
        title="Rerieve the Parent-Directory of a URL as a String"
    )
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(String urlAsStr)
    { return DotDots.parentDir(urlAsStr, '/', (short) 1); }


    /**
     * <BR>See Docs: Method {@link #dotDotParentDirectory(String, char, short)}
     * <BR>Converts: {@code URL} to {@code String}, eliminates non-essential
     * {@code URI}-information (such as Query-Strings, etc.)
     * <BR>Passes: A Separator-Character {@code char '/'} - the separator used in {@code URL's}
     */
    @IntoHTMLTable(
        background=BlueDither,
        title="Rerieve the n<SUP>th</SUP> Ancestory-Directory of a URL"
    )
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(URL url, short nLevels)
    {
        final String urlStr = url.getProtocol() + "://" + url.getHost() + url.getPath();
        return DotDots.parentDir(urlStr, '/', nLevels);
    }


    /** 
     * <BR>See Docs: Method {@link #dotDotParentDirectory(String, char, short)}
     * <BR>Passes: {@code char '/'}, the separator character used in {@code URL's}
     */
    @IntoHTMLTable(
        background=GreenDither,
        title="Rerieve the n<SUP>th</SUP> Ancestory-Directory of a URL as a String"
    )
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(String urlAsStr, short nLevels)
    { return DotDots.parentDir(urlAsStr, '/', nLevels); }


    /**
     * <BR>See Docs: Method {@link #dotDotParentDirectory(String, char, short)}
     * <BR>Passes: {@code '1'} to parameter {@code nLevels} - only going up one directory.
     */ 
    @IntoHTMLTable(
        background=BlueDither,
        title="Rerieve the Parent-Directory from String, use a Specified Separator-Char"
    )
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(String directoryStr, char dirSeparator)
    { return DotDots.parentDir(directoryStr, dirSeparator, (short) 1); }


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_DESC>
     * @param directoryStr  <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_DSTR> 
     * @param separator     <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_SEP>
     * @param nLevels       <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_NLVL> 
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_RET> 
     * 
     * @throws IllegalArgumentException
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_DOTDOT_PD_IAEX> 
     */
    @LinkJavaSource(handle="DotDots", name="parentDir")
    public static String dotDotParentDirectory(String directoryStr, char separator, short nLevels)
    { return DotDots.parentDir(directoryStr, separator, nLevels); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Quick 'isNumber' methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SPA_IS_INTEGER_DESC>
     * @param s Any java {@code String}
     * @return  <EMBED CLASS='external-html' DATA-FILE-ID=SPA_IS_INTEGER_RET>
     * @see     #isInt(String)
     */
    @LinkJavaSource(handle="IOPT", name="isInteger")
    public static boolean isInteger(String s)
    { return IsOfPrimitiveType.isInteger(s); }


    /** <BR>Passes: The ASCII characters that comprise {@code Integer.MIN_VALUE} */
    @IntoHTMLTable(
        background=BlueDither,
        title="Check if a Java-String Comprises a Valid Integer"
    )
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="INT_MIN_VALUE_DIGITS_AS_CHARS")
    @LinkJavaSource(handle="IOPT", name="check")
    public static boolean isInt(String s)
    { return IsOfPrimitiveType.check(s, IsOfPrimitiveType.INT_MIN_VALUE_DIGITS_AS_CHARS); }


    /** <BR>Passes: The ASCII characters that comprise {@code Long.MIN_VALUE} */
    @IntoHTMLTable(
        background=GreenDither,
        title="Check if a Java-String Comprises a Valid Long-Integer"
    )
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="LONG_MIN_VALUE_DIGITS_AS_CHARS")
    @LinkJavaSource(handle="IOPT", name="check")
    public static boolean isLong(String s)
    { return IsOfPrimitiveType.check(s, IsOfPrimitiveType.LONG_MIN_VALUE_DIGITS_AS_CHARS); }


    /** <BR>Passes: ASCII characters that comprise {@code Byte.MIN_VALUE} */
    @IntoHTMLTable(
        background=BlueDither,
        title="Check if a Java-String Comprises a Valid Byte"
    )
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="BYTE_MIN_VALUE_DIGITS_AS_CHARS")
    @LinkJavaSource(handle="IOPT", name="check")
    public static boolean isByte(String s)
    { return IsOfPrimitiveType.check(s, IsOfPrimitiveType.BYTE_MIN_VALUE_DIGITS_AS_CHARS); }


    /** <BR>Passes: ASCII characters that comprise {@code Short.MIN_VALUE} */
    @IntoHTMLTable(
        background=GreenDither,
        title="Check if a Java-String Comprises a Valid Short-Integer"
    )
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="SHORT_MIN_VALUE_DIGITS_AS_CHARS")
    @LinkJavaSource(handle="IOPT", name="check")
    public static boolean isShort(String s)
    { return IsOfPrimitiveType.check(s, IsOfPrimitiveType.SHORT_MIN_VALUE_DIGITS_AS_CHARS); }


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SPA_IS_PRMTYPE_DESC>
     * @param s Any Java <CODE>String</CODE>
     * @param minArr    <EMBED CLASS='external-html' DATA-FILE-ID=SPA_IS_PRMTYPE_MARR>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SPA_IS_PRMTYPE_RET>
     * @see #isInteger(String)
     * @see #isInt(String)
     * @see #isByte(String)
     * @see #isLong(String)
     * @see #isShort(String)
     */
    @LinkJavaSource(handle="IOPT", name="check")
    protected static boolean isOfPrimitiveType(String s, char[] minArr)
    { return IsOfPrimitiveType.check(s, minArr); }


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_FLOAT_PT_REGEX>
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRP_D_VALUEOF>
     * @see #floatingPointPred
     * @see #isDouble(String)
     */
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="FLOATING_POINT_REGEX")
    public static final Pattern FLOATING_POINT_REGEX = IsOfPrimitiveType.FLOATING_POINT_REGEX;


    /**
     * This is the floating-point regular-expression, simply converted to a predicate.
     * @see #FLOATING_POINT_REGEX
     * @see #isDouble(String)
     */
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="FLOATING_POINT_REGEX")
    public static final Predicate<String> floatingPointPred =
        IsOfPrimitiveType.FLOATING_POINT_REGEX.asPredicate();


    /**
     * Tests whether an input-{@code String} can be parsed into a {@code double}
     * @return <EMBED CLASSS='external-html' DATA-FILE-ID=SPA_IS_DOUBLE_RET>
     * @see #FLOATING_POINT_REGEX
     * @see #floatingPointPred
     */
    @LinkJavaSource(handle="IOPT", entity=FIELD, name="FLOATING_POINT_REGEX")
    public static boolean isDouble(String s)
    { return floatingPointPred.test(s); }
}