package Torello.Java;

import Torello.JavaDoc.LinkJavaSource;

import Torello.Java.ReadOnly.ReadOnlyArrayList;
import Torello.Java.ReadOnly.ReadOnlyList;

import Torello.Java.Function.IntTFunction;
import static Torello.Java.C.RESET;

import java.util.Calendar;
import java.util.Locale;
import java.util.Arrays;

import java.text.DecimalFormat;

/**
 * This class provides several {@code String} printing utilities such as abbreviation and list
 * printing.
 */
@Torello.JavaDoc.StaticFunctional
public class StrPrint
{
    private StrPrint() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // HELPER & BASIC
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_NLAT_DESC>
     * 
     * @param s Any {@code java.lang.String}, preferably one with multiple lines of text.
     * 
     * @return A {@code String}, where each line of text has been "trimmed", and the two
     * character sequence {@code "\\n"} inserted in-between each line.
     * 
     * @see #abbrevStartRDSF(String, int, boolean)
     * @see #abbrevEndRDSF(String, int, boolean)
     */
    public static String newLinesAsText(String s)
    {
        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();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviating Text, with "newLinesAsText" - Helper
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B>
     * <BR />Invokes:    {@link StringParse#removeDuplicateSpaces(String)} 
     * <BR />Or Invokes: {@link #newLinesAsText(String)}
     * <BR />Finally:    {@link #abbrevStart(String, boolean, int)}
     */
    public static String abbrevStartRDSF
        (String s, int maxLength, boolean seeEscapedNewLinesAsText)
    {
        // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios
        // of this conditional-statement, the new-lines have already been removed by the previous
        // method call.
        //
        // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines

        return seeEscapedNewLinesAsText
            ? abbrevStart(newLinesAsText(s), false, maxLength)
            : abbrevStart(StringParse.removeDuplicateSpaces(s), false, maxLength);
    }

    /**
     * Convenience Method.
     * <BR /><B STYLE='color: red;'>RDSF: Remove Duplicate Spaces First</B>
     * <BR />Invokes: {@link StringParse#removeDuplicateSpaces(String)}
     * <BR />Or Invokes: {@link #newLinesAsText(String)}
     * <BR />Finally: {@link #abbrevEnd(String, boolean, int)}
     */
    public static String abbrevEndRDSF
        (String s, int maxLength, boolean seeEscapedNewLinesAsText)
    {
        // false is passed to 'abbrevStart' parameter 'escapeNewLines' because in both scenarios
        // of this conditional-statement, the new-lines have already been removed by the previous
        // method call.
        //
        // both 'removeDuplicateSpaces' and 'newLinesAsText' remove the new-lines

        return seeEscapedNewLinesAsText
            ? abbrevEnd(newLinesAsText(s), false, maxLength)
            : abbrevEnd(StringParse.removeDuplicateSpaces(s), false, maxLength);
    }

    /**
     * Convenience Method.
     * <BR />Passes: {@code '0'} to parameter {@code 'abbrevPos'}, forcing the abbreviation to
     * occur at the <B>start</B> of the {@code String} (if long enough to be abbreviated)
     * <BR />See Documentation: {@link #abbrev(String, int, boolean, String, int)}
     */
    @LinkJavaSource(handle="Abbrev", name="print1")
    public static String abbrevStart(String s, boolean escNewLines, int maxLength)
    { return Abbrev.print1(s, 0, escNewLines, null, maxLength); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_1_DESC>
     * @param s This may be any Java (non-null) {@code String}
     *
     * @param abbrevPos This parameter is used to indicate where the abbreviation-{@code String}
     * should occur - <I>if this {@code String 's'} is long enough to be abbreviated.</I>  For
     * instance, if {@code '0'} (zero) were passed to this parameter, and {@code 's'} were longer
     * than parameter {@code 'maxLength'}, then an ellipsis would be appended to the beginning of
     * the returned-{@code 'String'}.  (Or, if some other {@code 'abbrevStr'} were specified, that
     * other abbreviation would be appended to the beginning of the returned-{@code String})
     * 
     * @param escapeNewLines            <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL>
     * @param abbrevStr                 <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR>
     * @param maxLength                 <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL>
     * @return                          <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_1_RET>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_1_IAEX>
     */
    @LinkJavaSource(handle="Abbrev", name="print1")
    public static String abbrev(
            String  s,
            int     abbrevPos,
            boolean escapeNewLines,
            String  abbrevStr,
            int     maxLength
        )
    { return Abbrev.print1(s, abbrevPos, escapeNewLines, abbrevStr, maxLength); }

    /**
     * Convenience Method.
     * <BR />Parameter: {@code spaceBeforeAbbrev} set to {@code FALSE}
     * <BR />Abbreviates: Default ellipsis ({@code '...'}) are placed at the end of the
     * {@code String}
     * <BR />See Documentation: {@link #abbrev(String, boolean, boolean, String, int)}
     */
    @LinkJavaSource(handle="Abbrev", name="print2")
    public static String abbrevEnd(String s, boolean escapeNewLines, int maxLength)
    { return Abbrev.print2(s, false, escapeNewLines, null, maxLength); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_2_DESC>
     * @param s This may be any Java (non-null) {@code String}
     *
     * @param spaceBeforeAbbrev This ensures that for whatever variant of ellipsis being used, the
     * space-character is inserted directly before appending the ellipsis {@code "..."} or the
     * user-provided {@code 'abbrevStr'}.
     *
     * @param escapeNewLines            <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_ENL>
     * @param abbrevStr                 <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_STR>
     * @param maxLength                 <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_MXL>
     * @return                          <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_2_RET>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=SP_ABBREV_2_IAEX>
     */
    @LinkJavaSource(handle="Abbrev", name="print2")
    public static String abbrev(
            String  s,
            boolean spaceBeforeAbbrev,
            boolean escapeNewLines,
            String  abbrevStr,
            int     maxLength
        )
    { return Abbrev.print2(s, spaceBeforeAbbrev, escapeNewLines, abbrevStr, maxLength); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviated List Printing
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'}
     * <BR />See Documentation: {@link #printListAbbrev(Iterable, IntTFunction, int, int, boolean,
     *  boolean, boolean)}
     */
    @LinkJavaSource(handle="PrintListAbbrev", name="print1")
    public static <ELEM> String printListAbbrev(
            Iterable<ELEM> list, int lineWidth, int indentation, boolean seeEscapedNewLinesAsText,
            boolean printNulls, boolean showLineNumbers
        )
    {
        return PrintListAbbrev.print1(
            list, (int i, Object o) -> o.toString(), lineWidth, indentation,
            seeEscapedNewLinesAsText, printNulls, showLineNumbers
        );
    }

    /**
     * <EMBED CLASS=defs DATA-LIST_TYPE=Array>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION>
     * @param list Any iterable-list of Java Object's
     * 
     * @param listItemPrinter
     * <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_LIST_ITEM_PR>
     * 
     * @param lineWidth                 <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_LINE_WIDTH>
     * @param indentation               <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_INDENTATION>
     * @param seeEscapedNewLinesAsText  <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_SEE_ESC_NL>
     * @param printNulls                <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_PRINT_NULLS>
     * @param showLineNumbers           <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_SHOW_LNUMS>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_RETURNS>
     * 
     * @see #zeroPad10e2(int)
     * @see #abbrevEndRDSF(String, int, boolean)
     * @see StringParse#nChars(char, int)
     * @see StringParse#trimLeft(String)
     */
    @LinkJavaSource(handle="PrintListAbbrev", name="print1")
    public static <ELEM> String printListAbbrev(
            Iterable<ELEM>                      list,
            IntTFunction<? super ELEM, String>  listItemPrinter,
            int                                 lineWidth,
            int                                 indentation,
            boolean                             seeEscapedNewLinesAsText,
            boolean                             printNulls,
            boolean                             showLineNumbers
        )
    {
        return PrintListAbbrev.print1(
            list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText,
            printNulls, showLineNumbers
        );
    }

    /**
     * Convenience Method.
     * <BR />Passes: {@code Object.toString()} to {@code 'listItemPrinter'}
     * <BR />See Documentation: {@link #printListAbbrev(Object[], IntTFunction, int, int, boolean,
     *      boolean, boolean)}
     */
    @LinkJavaSource(handle="PrintListAbbrev", name="print2")
    public static <ELEM> String printListAbbrev(
            ELEM[]  arr,
            int     lineWidth,
            int     indentation,
            boolean seeEscapedNewLinesAsText,
            boolean printNulls,
            boolean showLineNumbers
        )
    {
        return PrintListAbbrev.print2(
            arr, (int i, Object o) -> o.toString(), lineWidth, indentation,
            seeEscapedNewLinesAsText, printNulls, showLineNumbers
        );
    }

    /**
     * <EMBED CLASS=defs DATA-LIST_TYPE=Array>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_PLA_DESCRIPTION>
     * @param list Any iterable-list of Java Object's
     * 
     * @param listItemPrinter
     * <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_LIST_ITEM_PR>
     * 
     * @param lineWidth                 <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_LINE_WIDTH>
     * @param indentation               <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_INDENTATION>
     * @param seeEscapedNewLinesAsText  <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_SEE_ESC_NL>
     * @param printNulls                <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_PRINT_NULLS>
     * @param showLineNumbers           <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_SHOW_LNUMS>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=SP_PLA_RETURNS>
     * 
     * @see #zeroPad10e2(int)
     * @see #abbrevEndRDSF(String, int, boolean)
     * @see StringParse#trimLeft(String)
     */
    @LinkJavaSource(handle="PrintListAbbrev", name="print2")
    public static <ELEM> String printListAbbrev(
            ELEM[]                              list,
            IntTFunction<? super ELEM, String>  listItemPrinter,
            int                                 lineWidth,
            int                                 indentation,
            boolean                             seeEscapedNewLinesAsText,
            boolean                             printNulls,
            boolean                             showLineNumbers
        )
    {
        return PrintListAbbrev.print2(
            list, listItemPrinter, lineWidth, indentation, seeEscapedNewLinesAsText,
            printNulls, showLineNumbers
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Line(s) of Text
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_LINE_OR_DESC>
     * 
     * @param s This may be any valid Java {@code String}.  It ought to be some variant of a
     * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both
     * directions, left and right</I> - from parameter {@code int 'pos'} and parameter
     * {@code int 'len'}
     * 
     * @param pos This is a position in the input-parameter {@code String 's'}.  The nearest
     * {@code '\n'} (new-line) character, <I>to the left</I> of this position, will be found and
     * identified.  If the {@code char} at {@code s.charAt(pos)} is, itself, a {@code '\n'}
     * (newline) character, then no left-direction search will be performed.  The left-most
     * position of the returned substring would then be {@code pos + 1}.
     * 
     * @param len The search for the 'right-most' {@code '\n'} (newline-character) will begin at
     * position {@code 'len'}.  If the character at {@code 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 {@code pos + len - 1}.
     * 
     * @param unixColorCode If this {@code String} is null, it will be ignored.  If this
     * {@code String} is non-null, it will be inserted before the "Matching {@code String}"
     * indicated by the index-boundaries {@code pos} <I>TO</I> {@code pos + len}.
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>Note:</B> No Validity Check shall be performed on this {@code String},
     * and the user is not obligated to provide a {@link C} valid UNIX Color-Code {@code String}.
     * Also, a closing {@code C.RESET} is inserted after the terminus of the match.
     * </DIV>
     * 
     * @return The {@code String} demarcated by the first new-line character PLUS 1
     * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1
     * <I><B>AFTER</I></B> index {@code pos + len}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_LINES_RET>
     * 
     * @throws StringIndexOutOfBoundsException If either {@code 'pos'}, or {@code 'pos + len'} are
     * not within the bounds of the input {@code String 's'}
     * 
     * @throws IllegalArgumentException If the value passed to parameter {@code 'len'} is zero or
     * negative.
     */
    public static String lineOrLines(String s, int pos, int len, String unixColorCode)
    {
        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) + 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);
                */
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_LINE_DESC>
     * 
     * @param s This may be any valid Java {@code String}.  It ought to be some variant of a
     * text-file. It will be searched for the nearest {@code '\n'} character - <I>in both
     * directions, left and right</I> - from parameter {@code int 'pos'}.
     * 
     * @param pos This is a position in the input-parameter {@code 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 {@code s.charAt(pos)} is itself a newline {@code '\n'}
     * character, then <I>an exception shall throw</I>.
     * 
     * @return The {@code String} identified by the first new-line character PLUS 1
     * <I><B>BEFORE</I></B> index {@code 'pos'}, and the first new-line character MINUS 1
     * <I><B>AFTER</I></B> index {@code 'pos + len'}.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_LINES_RET>
     * 
     * @throws StringIndexOutOfBoundsException If {@code 'pos'} is not within the bounds of the 
     * input {@code String 's'}
     * 
     * @throws IllegalArgumentException If the character in {@code String 's'} at position
     * {@code 'pos'} is a newline {@code '\n'}, itself.
     */
    public static String line(String s, int pos)
    {
        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, lineEnd;

        // Prevents StrIndexOf from throwing StringINdexOutOfBounds
        if (pos == 0) lineStart = 0;

        // Also prevent lineStart equal-to '-1'
        else if ((lineStart = StrIndexOf.left(s, pos, '\n')) == -1) lineStart = 0;

        // Prevent lineEnd equal to '-1'
        if ((lineEnd = s.indexOf('\n', pos)) == -1) lineEnd = s.length();

        // if this is the first line, there was no initial '\n', so don't skip it!
        return (lineStart == 0)

            // This version returns the String from the position-0 (Pay Attention!)
            ? s.substring(0, lineEnd)

            // This version simply eliminates the '\n' that is in the directly-preceeding character
            : s.substring(lineStart + 1, lineEnd);
    }

    /**
     * This will retrieve the first {@code 'n'} lines of a {@code String} - where a line is defined
     * as everything up to and including the next newline {@code '\n'} character.
     * 
     * @param s Any java {@code String}.
     * 
     * @param n This is the number of lines of text to retrieve.
     * 
     * @return a substring of s where the last character in the {@code String} is a {@code '\n'}.
     * The last character should be the nth {@code '\n'} character found in s.  If there is no such
     * character, then the original {@code String} shall be returned instead.
     * 
     * @throws NException This exception shall throw if parameter {@code 'n'} is less than 1, or
     * longer than {@code s.length()}.
     */
    public static String firstNLines(String s, int n)
    {
        NException.check(n, s);
        int pos = StrIndexOf.nth(s, n, '\n');

        if (pos != -1)  return s.substring(0, pos + 1);
        else            return s;
    }

    /**
     * This will retrieve the last 'n' lines of a {@code String} - where a line is defined as
     * everything up to and including the next newline {@code '\n'} character.
     * 
     * @param s Any java {@code String}.
     * 
     * @param n This is the number of lines of text to retrieve.
     * 
     * @return a substring of {@code 's'} where the last character in the {@code String} is a
     * new-line character {@code '\n'}, and the first character is the character directly before
     * the nth newline {@code '\n'} found in {@code 's'} - starting the count at the end of the
     * {@code String}.  If there is no such substring, then the original {@code String} shall be
     * returned.
     * 
     * @throws NException This exception shall throw if {@code 'n'} is less than 1, or longer
     * {@code s.length()}.
     */
    public static String lastNLines(String s, int n)
    {
        NException.check(n, s);
        int pos = StrIndexOf.nthFromEnd(s, n, '\n');

        if (pos != -1)  return s.substring(pos + 1);
        else            return s;
    }

    /**
     * This is used for "trimming each line" of an input {@code 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 {@code String} by new-line characters, and then trim each
     * line, and afterward rebuild the {@code String} and return it. 
     * 
     * <BR /><BR /><DIV CLASS=JDHint>
     * <B STYLE='color:red;'>CRLF Issues:</B> This will only split the {@code String} using the
     * standard {@code '\n'} character.  If the {@code String} being used uses {@code '\r'} or
     * {@code '\n\r'}, use a different trim method.
     * </DIV>
     * 
     * @param str This may be any {@code String}.  It will be split by new-line characters
     * {@code '\n'}
     * 
     * @return Returns the rebuilt {@code String}, with each line having a {@code String.trim();}
     * operation performed.
     */
    public static String trimEachLine(String str)
    {
        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();
    }

    /**
     * Interprets an input {@code String} as one which was read out of a Text-File.  Counts the
     * number of new-line ({@code '\n'}) characters between {@code String} indices {@code '0'} and
     * {@code 'pos'}
     * 
     * <BR /><BR />This is intended be the Line-Number where {@code String}-Index parameter
     * {@code 'pos'} is located inside the {@code 'str'} (presuming {@code 'str'} was retrieved
     * from a Text-File).
     * 
     * @param str Any Java {@code String}, preferably one with multiple lines of text.
     * @param pos Any valid {@code String}-Index that occurs ithin {@code 'str'}
     * 
     * @return The Line-Number within Text-File parameter {@code 'str'} which contains
     * {@code String}-Index parameter {@code 'pos'}
     * 
     * @throws StringIndexOutOfBoundsException If integer-parameter {@code 'pos'} is negative or
     * past the length of the {@code String}-Parameter {@code 'str'}.
     * 
     * @see #lineNumberSince(String, int, int, int)
     */
    public static int lineNumber(String str, int pos)
    {
        if (pos < 0) throw new StringIndexOutOfBoundsException
            ("The number provided to index parameter 'pos' : [" + pos + "] is negative.");

        if (pos >= str.length()) throw new StringIndexOutOfBoundsException(
            "The number provided to index parameter 'pos' : [" + pos + "] is greater than the " +
            "length of the input String-Parameter 'str' [" + str.length() + "]."
        );

        int lineNum = 1;

        for (int i=0; i <= pos; i++) if (str.charAt(i) == '\n') lineNum++;

        return lineNum;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_LINE_SINCE_DESC>
     * 
     * @param str Any Java {@code String}.  This {@code String} will be interpreted as a Text-File
     * whose newline characters ({@code '\n'} chars) represent lines of text.
     * 
     * @param pos Any valid {@code String}-index within {@code 'str'}
     * 
     * @param prevLineNum This should be the Line-Number that contains the {@code String}-index
     * {@code 'prevPos'}
     * 
     * @param prevPos This may be any index contained by {@code String} parameter {@code 'str'}.
     * It is expected that this parameter be an index that occured on Line-Number
     * {@code 'prevLineNum'} of the Text-File {@code 'str'}
     * 
     * @return The Line-Number within Text-File parameter {@code 'str'} that contains
     * {@code String}-index {@code 'pos'}
     * 
     * @throws IllegalArgumentException If {@code 'pos'} is less than or equal to
     * {@code 'prevPos'}, or if {@code 'prevLineNum'} is less than zero.
     * 
     * @see #lineNumber(String, int)
     */
    public static int lineNumberSince(String str, int pos, int prevLineNum, int prevPos)
    {
        if (pos <= prevPos) throw new IllegalArgumentException(
            "The number provided to index parameter 'pos' : [" + pos + "] is less than or equal " +
            "to previous-match index-parameter prevPos : [" + prevPos + "]"
        );

        if (prevLineNum < 0) throw new IllegalArgumentException(
            "You have provided a negative number to Line-Number parameter 'prevLineNum' : " +
            "[" + prevLineNum + "]"
        );

        for (int i = (prevPos + 1); i <= pos; i++) if (str.charAt(i) == '\n') prevLineNum++;

        return prevLineNum;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abbreviation: Line-Length **AND** Number of Lines
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WHA_DESCRIPTION>
     * 
     * @param s                 Any Java {@code String}
     * @param horizAbbrevStr    <EMBED CLASS='external-html' DATA-FILE-ID=SP_WHA_H_ABBREV_STR>
     * @param maxLineLength     <EMBED CLASS='external-html' DATA-FILE-ID=SP_WHA_MAX_LINE_LEN>
     * @param maxNumLines       <EMBED CLASS='external-html' DATA-FILE-ID=SP_WHA_MAX_NM_LINES>
     * 
     * @param compactConsecutiveBlankLines When this parameter is passed {@code TRUE}, any 
     * series of Empty-Lines, or lines only containing White-Space will be compacted to a single 
     * line of text that simply states {@code "[Compacted 10 Blank Lines]"} (or however many 
     * White-Space-Only Lines were actually compacted, if that number isn't {@code '10'})
     * 
     * @return                          The modified {@code String}.
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=SP_WHA_IAEX>
     */
    @LinkJavaSource(handle="VertAndHorizAbbrev")
    public static String widthHeightAbbrev(
            final String    s,
            final String    horizAbbrevStr,
            final Integer   maxLineLength,
            final Integer   maxNumLines,
            final boolean   compactConsecutiveBlankLines
        )
    {
        return VertAndHorizAbbrev.print
            (s, horizAbbrevStr, maxLineLength, maxNumLines, compactConsecutiveBlankLines);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Wrap Text to another line
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #wrap(String, int, int)}
     * <BR />Passes same {@code 'lineLen'} value to <B><I>BOTH</I></B> Line-Length Parameters
     */
    @LinkJavaSource(handle="Wrap")
    @LinkJavaSource(handle="WrapHelpers")
    public static String wrap(String s, int lineLen)
    { return Wrap.wrap(s, lineLen, lineLen); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_DESCRIPTION>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_RIGHT_TRIM>
     * 
     * @param s             Any Java {@code String}; may not contain {@code '\t', '\f' or '\r'}
     * @param firstLineLen  <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_1ST_LN_LEN>
     * @param lineLen       The maximum allowable Line-Length for all other lines of text.
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_RETURNS>
     * 
     * @throws StringFormatException <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_STR_FMT_EX>
     * @throws IllegalArgumentException If {@code 'firstLineLen'} or {@code 'lineLen'} are
     * zero or negative.
     */
    @LinkJavaSource(handle="Wrap")
    @LinkJavaSource(handle="WrapHelpers")
    public static String wrap(String s, int firstLineLen, int lineLen)
    { return Wrap.wrap(s, firstLineLen, lineLen); }
 

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #wrapToIndentation(String, int, int)}
     * <BR />Passes same {@code 'lineLen'} value to <B><I>BOTH</I></B> Line-Length Parameters
     */
    @LinkJavaSource(handle="WrapToIndentation")
    @LinkJavaSource(handle="WrapHelpers")
    public static String wrapToIndentation(String s, int lineLen)
    { return WrapToIndentation.wrap(s, lineLen, lineLen); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_DESCRIPTION>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_RIGHT_TRIM>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_TO_INDENT>
     * 
     * @param s             Any Java {@code String}; may not contain {@code '\t', '\f' or '\r'}
     * @param firstLineLen  <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_1ST_LN_LEN>
     * @param lineLen       The maximum allowable Line-Length for all other lines of text.
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_RETURNS>
     * 
     * <BR /><BR />As already explained, the returned {@code String} shall contain "wrapped" text 
     * which has an amount of indentation (space characters) equal to whatever line is directly
     * above it.  Indented lines, effectively, "inherit" the amount of indentation present in the 
     * line coming directly before them.
     * 
     * @throws StringFormatException <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_STR_FMT_EX>
     * @throws IllegalArgumentException If {@code 'firstLineLen'} or {@code 'lineLen'} are
     * zero or negative.
     */
    @LinkJavaSource(handle="WrapToIndentation")
    @LinkJavaSource(handle="WrapHelpers")
    public static String wrapToIndentation(String s, int firstLineLen, int lineLen)
    { return WrapToIndentation.wrap(s, firstLineLen, lineLen); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_DESCRIPTION>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_RIGHT_TRIM>
     * 
     * @param s             Any Java {@code String}; may not contain {@code '\t', '\f' or '\r'}
     * @param firstLineLen  <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_1ST_LN_LEN>
     * @param lineLen       The maximum allowable Line-Length for all other lines of text.
     * 
     * @param extraSpaces   Wrapped text will get an additional amount of indentation, past 
     *                      any and all inherited indentation
     * @return Wrapped.
     * 
     * @throws StringFormatException <EMBED CLASS='external-html' DATA-FILE-ID=SP_WRAP_STR_FMT_EX>
     * @throws IllegalArgumentException If {@code 'firstLineLen'} or {@code 'lineLen'} are
     * zero or negative.
     */
    @LinkJavaSource(handle="WrapToIndentationPlus")
    @LinkJavaSource(handle="WrapHelpers")
    public static String wrapToIndentationPlus
        (String s, int firstLineLen, int lineLen, int extraSpaces)
    { return WrapToIndentationPlus.wrap(s, firstLineLen, lineLen, extraSpaces); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Misc Date String Functions
    // ********************************************************************************************
    // ********************************************************************************************


    private static final Calendar internalCalendar = Calendar.getInstance();

    /**
     * Generates a "Date String" using the character separator {@code '.'}  
     * @return A {@code String} in the form: {@code YYYY.MM.DD}
     */
    public static String dateStr() { return dateStr('.', false); }

    /**
     * Generates a "Date String" using the <I>separator</I> parameter as the separator between
     * numbers
     * 
     * @param separator Any ASCII or UniCode character.
     * 
     * @return A {@code String} of the form: {@code YYYYcMMcDD} where {@code 'c'} is the passed
     * {@code 'separator'} parameter.
     */
    public static String dateStr(char separator) { return dateStr(separator, false); }

    /**
     * Generates a "Date String" that is consistent with the directory-name file-storage locations
     * used to store articles from {@code http://Gov.CN}.
     * 
     * @return The {@code String's} used for the Chinese Government Web-Portal Translation Pages
     */
    public static String dateStrGOVCN() { return dateStr('/', false).replaceFirst("/", "-"); }
    // "2017-12/05"

    /**
     * This class is primary included because although Java has a pretty reasonable "general
     * purpose" calendar class/interface, but a consistent / same {@code String} since is needed
     * because the primary use here is for building the names of files.
     *
     * @param separator Any ASCII or Uni-Code character.
     * 
     * @param includeMonthName When <I>TRUE</I>, the English-Name of the month ({@code 'January'}
     * ... {@code 'December'}) will be appended to the month number in the returned {@code String}.
     * 
     * @return The year, month, and day as a {@code String}.
     */
    public static String dateStr(char separator, boolean includeMonthName)
    {
        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);

        return (separator != 0)
            ? (c.get(Calendar.YEAR) + "" + separator + m + separator + d)
            : (c.get(Calendar.YEAR) + "" + m + d);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Misc Month-Date String Functions
    // ********************************************************************************************
    // ********************************************************************************************


    /** The months of the year, as an immutable list of {@code String's}. */
    public static final ReadOnlyList<String> months = new ReadOnlyArrayList<>(
        "January", "February", "March", "April", "May", "June",
        "July", "August", "September", "October", "November", "December"
    );

    /**
     * Converts an integer into a Month.
     * @param month The month, as a number from {@code '1'} to {@code '12'}.
     * @return A month as a {@code String} like: {@code "January"} or {@code "August"}
     * @see #months
     */
    public static String monthStr(int month) { return months.get(month); }

    /**
     * Returns a {@code String} that has the year and the month (but not the day, or any other
     * time related components).
     *
     * @return Returns the current year and month as a {@code String}.
     */
    public static String ymDateStr() { return ymDateStr('.', false); }

    /**
     * Returns a {@code String} that has the year and the month (but not the day, or other time
     * components).
     * 
     * @param separator The single-character separator used between year, month and day.
     * @return The current year and month as a {@code String}.
     */
    public static String ymDateStr(char separator) { return ymDateStr(separator, false); }

    /**
     * Returns a {@code String} that has the year and the month (but not the day, or other time
     * components).
     * 
     * @param separator The single-character separator used between year, month and day.
     * 
     * @param includeMonthName When this is true, the name of the month, in English, is included
     * with the return {@code String}.
     * 
     * @return {@code YYYY<separator>MM(? include-month-name)}
     */
    public static String ymDateStr(char separator, boolean includeMonthName)
    {
        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);

        return (separator != 0)
            ? (c.get(Calendar.YEAR) + "" + separator + m)
            : (c.get(Calendar.YEAR) + "" + m);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Misc Time String Functions
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns the current time as a {@code String}.
     * 
     * @return military time - with AM|PM (redundant) added too.
     * Includes only Hour and Minute - separated by a colon character {@code ':'}
     * 
     * @see #timeStr(char)
     */
    public static String timeStr() { return timeStr(':'); }

    /**
     * Returns the current time as a {@code String}.
     * @param separator The character used to separate the minute &amp; hour fields
     * @return military time - with AM|PM added redundantly, and a separator of your choosing.
     */
    public static String timeStr(char separator)
    {
        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";

        return (separator != 0)
            ? (h + separator + m + separator + p)
            : (h + m + p);
    }

    /**
     * Returns the current time as a {@code String}.  This method uses all time components
     * available.
     * 
     * @return military time - with AM|PM added redundantly.
     */
    public static String timeStrComplete()
    {
        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";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // More Numeric Methods
    // ********************************************************************************************
    // ********************************************************************************************


    private static final DecimalFormat formatter = new DecimalFormat("#,###");

    /**
     * Makes a {@code long} number like {@code 123456789} into a number-string such as:
     * {@code "123,456,789"}. Java's {@code package java.text.*} is easy to use, and versatile, but
     * the commands are not always so easy to remember.
     *
     * @param l Any {@code long} integer.  Comma's will be inserted for every third power of ten
     * 
     * @return After calling java's {@code java.text.DecimalFormat} class, a {@code String}
     * representing this parameter will be returned.
     */
    public static String commas(long l)
    { return formatter.format(l); }

    /**
     * The words "ordinal indicator" are referring to the little character {@code String} that is
     * often used in English to make a number seem more a part of an english sentence.
     * 
     * @param i Any positive integer (greater than 0)
     *
     * @return This will return the following strings:
     * 
     * <TABLE CLASS=JDBriefTable>
     * <TR><TH>Input:   </TH><TH>RETURNS:</TH></TR>
     * <TR><TD>i = 1    </TD><TD>"st" &nbsp;(as in "1st","first")   </TD></TR>
     * <TR><TD>i = 2    </TD><TD>"nd" &nbsp;(as in "2nd", "second") </TD></TR>
     * <TR><TD>i = 4    </TD><TD>"th" &nbsp;(as in "4th")           </TD></TR>
     * <TR><TD>i = 23   </TD><TD>"rd" &nbsp;(as in "23rd")          </TD></TR>
     * </TABLE>
     * 
     * @throws IllegalArgumentException If i is negative, or zero
     */
    public static String ordinalIndicator(int i)
    {
        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";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Zero Padding stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZERO_PAD_DESC>
     * @param n Any Integer.  If {@code 'n'} is negative or greater than 1,000 - null is returned.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZERO_PAD_RET>
     * @see #zeroPad10e2(int)
     * @see #zeroPad10e4(int)
     */
    public static String zeroPad(int n)
    {
        if (n < 0)      return null;
        if (n < 10)     return "00" + n;
        if (n < 100)    return "0" + n;
        if (n < 1000)   return "" + n;
        return null;
    }

    /**
     * Pads an integer such that it contains enough leading zero's to ensure a
     * {@code String}-length of two.
     * 
     * @param n Must be an integer between 0 and 99, or else null will be returned
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZP_10E2_RET>
     * @see #zeroPad(int)
     */
    public static String zeroPad10e2(int n)
    {
        if (n < 0)      return null;
        if (n < 10)     return "0" + n;
        if (n < 100)    return "" + n;
        return null;
    }

    /**
     * Pads an integer such that it contains enough leading zero's to ensure a String-length of
     * four.
     * 
     * @param n Must be an integer between 0 and 9999, or else null will be returned
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZP_10E4_RET>
     * @see #zeroPad(int)
     */
    public static String zeroPad10e4(int n)
    {
        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;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZP_POW2_DESC>
     * 
     * @param n Must be an integer between {@code '0'} and {@code '9999'} where the number of 
     * {@code '9'} digits is equal to the value of parameter {@code int 'powerOf10'}
     * 
     * @param powerOf10 This must be a positive integer greater than {@code '1'}.  It may not be 
     * larger {@code '11'}.  The largest value that any integer in Java may attain is
     * {@code '2,147,483, 647'}
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=SP_ZP_POW2_RET>
     * 
     * @throws IllegalArgumentException if the value parameter {@code 'powerOf10'} is less than 2,
     * or greater than {@code 11}.
     */
    public static String zeroPad(int n, int powerOf10)
    {
        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);
    }

}