package Torello.Java;

import Torello.Java.Function.*;
import Torello.JavaDoc.LinkJavaSource;

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

/**
 * A utility that builds Comma Separated Value String's (and can parse them as well).
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=STR_CSV>
 */
@Torello.JavaDoc.StaticFunctional
public class StrCSV
{
    private StrCSV() { }

    // Package-Private: Exception-Message Helper used by the Helper-CSV Classes
    static void throwNPE(int i, Object o)
    {
        throw new NullPointerException(
            "The toString Lambda provided to this method returned null for array-index " +
            "[" + i + "].  At this index, the array contents were [" + o.toString() + "]"
        );
    }

    // Package-Private: Exception-Message Helper used by the Helper-CSV Classes
    static final String IAE_MESSAGE_MAXLENINNER =
        "The value passed to parameter 'maxLengthInner' was [TOK].  " +
        "However, BECAUSE this value represents a minimum String length for a subarray, " +
        "AND BECAUSE an ellipsis, space and brackets are appended, this parameter may not " +
        "have a positive value less than 7.";


    // ********************************************************************************************
    // ********************************************************************************************
    // From CSV to Array
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #CSV(String, boolean, boolean)}.
     */
    public static String[] CSV(String s) { return CSV(s, true, true); }

    /**
     * This will return a list of {@code String} that are in-between each-and-every comma that is
     * found inside the parameter-{@code String} {@code 's'}
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Java Stream API:</B>
     * 
     * <BR />This method uses Java 8 or 9's {@code package java.util.stream.*}.  If this package is
     * not familiar, it is usually just a way (after some practice), of (sort-of) converting
     * for-loops into more readable method-calls.  Java-Streams instead substitute words such as:
     * {@code 'filter', 'map', 'forEach'} and {@code 'toArray'}. This method's code is nothing more
     * than that.
     *
     * @param s This accepts any java-{@code String}, but it is expecting one that contains commas.
     * 
     * @param performTrim If this parameter is set to {@code TRUE}, then all {@code String's} will
     * be trimmed of white-space before being placed in the returned {@code String}-array, by
     * calling Java's {@code String.trim()} method.
     * 
     * @param eliminateZeroLengthStrings If this parameter is set to {@code TRUE}, then all 
     * {@code String's} that have zero-length will be eliminated from the returned {@code String[]}
     * array.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">NOTE:</B></SPAN> Regardless of whether or not a
     * {@code trim()} operation was performed, all {@code String's} that are trimmed of
     * white-space, would have the {@code 'trim'} done <B><I>before</B></I> the {@code 'eliminate'}
     * operation.
     * 
     * @return This will return the individual {@code String's} from a larger-{@code String} that
     * contained comma-separated values.
     */
    public static String[] CSV(String s, boolean performTrim, boolean eliminateZeroLengthStrings)
    {
        Stream<String> stream =
            StringParse.COMMA_REGEX.splitAsStream(s).filter((String csv) -> csv != null);

        if (performTrim)
            stream = stream.map((String csv) -> csv.trim());

        if (eliminateZeroLengthStrings)
            stream = stream.filter((String csv) -> csv.length() > 0);

        return stream.toArray(String[]::new);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // To CSV, Object Arrays, Iterables
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(Iterable, boolean, boolean, Integer)}
     * <BR />Converts: {@code String[] Array} to {@code List<String>}.
     */
    @LinkJavaSource(handle="IterableCSV", name="toCSV1")
    public static String toCSV(String[] sArr, boolean trim, boolean printNulls, Integer maxLength)
    { return IterableCSV.toCSV1(Arrays.asList(sArr), trim, printNulls, maxLength); }

    /**
     * This method will turn the elements of any java {@code Iterable} type into a 
     * {@code java.lang.String}.  The returned {@code String} shall have the individual elements
     * of parameter {@code 'i'} converted to {@code String's}, each separated by a comma.
     * 
     * @param i Any Java {@code Iterable}.  The Java {@code Object.toString()} will be invoked on
     * each of the elements produced by the {@code Iterable}, and commas shall be inserted between
     * each element.
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=RAWTYPES>
     * 
     * @param trim This is a boolean, and when set {@code TRUE}, the {@code String.trim()} shall be
     * invoked on each {@code String} inserted into the CSV list before insertion.
     * 
     * @param printNulls This is a boolean, and when set {@code TRUE}, each object returned by the
     * iterator shall be checked for a 'null' value before insertion into the output-{@code String}
     * - <I>to avoid null-pointer exceptions</I>.  Instead the four-character {@code String} 'null'
     * will be inserted instead of throwing this exception.
     * 
     * <BR /><BR />When this parameter receives {@code FALSE}, if the input parameter
     * {@code Iterable<?> i} contains a null value, then this method will simply throw a 
     * {@code NullPointerException}.
     * 
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * 
     * @return This will return a CSV {@code String} containing the individual elements of the
     * input {@code Iterable} parameter {@code 'i'}, where each element has been converted to a
     * {@code String} and is separated by a comma.
     * 
     * @throws NullPointerException If the {@code Iterable} returns a null value, and the
     * {@code 'printNulls'} parameter were set to {@code FALSE}, then this method would throw
     * an exception.
     */
    @LinkJavaSource(handle="IterableCSV", name="toCSV1")
    public static String toCSV(Iterable<?> i, boolean trim, boolean printNulls, Integer maxLength)
    { return IterableCSV.toCSV1(i, trim, printNulls, maxLength); }

    /**
     * This method will turn the elements of any java {@code Iterable} type into a 
     * {@code java.lang.String}.  The returned {@code String} shall have the individual elements
     * of parameter {@code 'i'} converted to {@code String's}, each separated by a comma.
     * 
     * @param <T> The type used by the {@code java.lang.Iterable}.  The {@code 'toString'} 
     * parameter / function-pointer also must accept this type, or a super-type.
     * 
     * @param i Any Java {@code Iterable}.  The functional-interface parameter {@code 'toString'}
     * will be invoked on each of the elements produced by the {@code Iterable}, and commas shall
     * be inserted between each element.
     * 
     * @param toString This instance of {@code java.util.function.Function<A, B>} must have a
     * method that accepts a parameter having type {@code 'T'}, and returns a {@code String}.  This
     * is simply an "over-riding" of Java's basic {@code 'toString()'} method.  In fact, if the
     * class that is being used for variable-type parameter {@code 'T'} has a {@code 'toString'}
     * method that is sufficient or "good enough", then this method should not be used, but
     * rather the simpler method: {@link #toCSV(Iterable, boolean, boolean, Integer)}.
     * 
     * @param printNulls When this parameter is {@code TRUE}, the {@code 'toString.apply(T)'}
     * method shall receive a null value, and the {@code String} results returned by this method
     * shall be inserted into the output {@code String} when the input {@code Iterable 'i'}
     * contains a null value.  Thusly, the behavior of this method for 'nulls' in the input
     * {@code 'i'} parameter should be <I>no different than any other value found within the input
     * {@code Iterable 'i'}.</I>
     * 
     * <BR /><BR />When this parameter receives {@code FALSE}, any time a null value is encountered
     * from the input {@code Iterable<T> 'i'}, that value shall be skipped and the output
     * {@code String} that is returned will have one fewer element in it's CSV list.
     * 
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * 
     * @return This will return a CSV {@code String} containing the individual elements of the
     * input {@code Iterable} parameter {@code 'i'}, where each element has been converted to a
     * {@code String} - <I>using the provided {@code 'toString'}</I> function - and is separated by
     * a comma.
     */
    @LinkJavaSource(handle="IterableCSV", name="toCSV2")
    public static <T> String toCSV(
            Iterable<T> i, Function<? super T, String> toString,
            boolean printNulls, Integer maxLength
        )
    { return IterableCSV.toCSV2(i, toString, printNulls, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(Object[], int, int, boolean, boolean, Integer)}
     */
    @LinkJavaSource(handle="TArr1D", name="toCSV1")
    public static <T> String toCSV
        (T[] tArr, boolean trim, boolean printNulls, Integer maxLength)
    { return TArr1D.toCSV1(tArr, 0, -1, trim, printNulls, maxLength); }

    /**
     * This method will turn the elements of any java {@code Iterable} type into a 
     * {@code java.lang.String}.  The returned {@code String} shall have the individual elements
     * of parameter {@code 'i'} converted to {@code String's}, each separated by a comma.
     * 
     * @param tArr Any array type {@code 'T'}.  Java's {@code 'toString'} method will be invoked
     * on each of these elements, and returned in a {@code String} where each element has been
     * separated by a comma.
     * 
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * 
     * @param trim This is a boolean, and when set {@code TRUE}, the {@code String.trim()} shall be
     * invoked on each {@code String} inserted into the CSV list before insertion.
     * 
     * @param printNulls This is a boolean, and when set {@code TRUE}, each instance of {@code 'T'}
     * contained by {@code 'tArr'} shall be checked for a 'null' value before insertion into the
     * output-{@code String} - <I>to avoid null-pointer exceptions</I>.  If a null is found, the
     * four-character {@code String} 'null' will be inserted instead of throwing this exception.
     * 
     * <BR /><BR />When this parameter receives {@code FALSE}, if a null value is encountered within
     * the input-parameter array {@code T[] tArr}, then this method will, in fact, throw a 
     * NullPointerException.
     * 
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * 
     * @return This will return a CSV {@code String} containing the individual elements of the
     * input array {@code T[] tArr} parameter, where each element shall have been converted to a
     * {@code String} and separated by a comma.
     * 
     * @throws NullPointerException If the {@code Iterable} returns a null value, and the
     * {@code 'printNulls'} parameter were set to {@code FALSE}, then this method would throw
     * an exception.
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     */
    @LinkJavaSource(handle="TArr1D", name="toCSV1")
    public static <T> String toCSV
        (T[] tArr, int sPos, int ePos, boolean trim, boolean printNulls, Integer maxLength)
    { return TArr1D.toCSV1(tArr, sPos, ePos, trim, printNulls, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(Object[], int, int, IntTFunction, boolean, Integer)}
     */
    @LinkJavaSource(handle="TArr1D", name="toCSV2")
    public static <T> String toCSV
        (T[] tArr, IntTFunction<? super T, String> toString, boolean printNulls, Integer maxLength)
    { return TArr1D.toCSV2(tArr, 0, -1, toString, printNulls, maxLength); }

    /**
     * Converts an array of a variable-type parameter {@code T[]} to a CSV {@code String}
     * 
     * <BR /><BR />This version of {@code 'toCSV'} allows a programmer to define the exact
     * {@code 'toString()'} that is used on each object-instance in the provided array.  There
     * is a simpler version of this method where the invokation {@code T.toString()} is 
     * used instead.
     * 
     * @param <T> The type used by the {@code T[]}-Array.  The {@code 'toString'}
     * parameter / function-pointer also must accept this type.
     * 
     * @param tArr An array of {@code Object's} of a given variable-type {@code 'T'}
     * @param sPos <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * 
     * @param toString A method that will convert {@code Object's} of type {@code 'T'} to a
     * {@code String}.  This parameter <I><B>may not</I></B> be null, because in such cases it
     * would be appropriate to use: {@link #toCSV(Object[], int, int, boolean, boolean, Integer)}
     * 
     * <BR /><BR /><B STYLE="color: red;">NOTE:</B> This functional-interface is used
     * instead of simply calling {@code Object.toString()} in order to allow a programmer to
     * provide arbitrarily defined {@code toString()} methods.  If the standard {@code toString()}
     * method for a given {@code Object} is not sufficient, then provide a different one here using
     * this parameter.
     * 
     * <BR /><BR />This {@code 'toString'} functional-interface is expected to accept both an
     * instance of a type {@code 'T'} variable, <B><I>AND</I></B> an integer.  The integer that is
     * accepted is simply the array-index where the {@code 'T'} variable parameter is located
     * within the array.
     * 
     * <BR /><BR /><B STYLE="color: red;">NOTE:</B> This function may return a zero-length
     * {@code String}, and when/if it does, the {@code Object} located at that array-index shall
     * not be printed to the output-{@code String}.  Also, if this function ever returns null, then
     * a {@code NullPointerException} shall throw immediately.
     * 
     * @param printNulls When this parameter is {@code TRUE}, if a null is encountered within the
     * input-parameter array {@code T[] tArr}, then null shall be passed to the Functional
     * Interface input-parameter method {@code toString.apply(T)}, and the {@code String} result
     * from that method shall be inserted into the {@code String} that is returned.
     * 
     * <BR /><BR />When this parameter receives {@code FALSE}, then anytime a null value is found
     * within the input-parameter array {@code T[] tArr}, it will be skipped completely, and the
     * output {@code String} will simply contain one fewer output-{@code String}.
     * 
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * 
     * @return a CSV version of the input parameter {@code 'tArr'} where each instance of
     * {@code 'T'} shall have been converted to a {@code String} using the provided
     * {@code 'toString(...)'} method.
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException if parameter {@code 'toString'} is null, or if any of the
     * return values produced by {@code 'toString'} are null
     */
    @LinkJavaSource(handle="TArr1D", name="toCSV2")
    public static <T> String toCSV(
            T[] tArr, int sPos, int ePos, IntTFunction<? super T, String> toString,
            boolean printNulls, Integer maxLength
        )
    { return TArr1D.toCSV2(tArr, sPos, ePos, toString, printNulls, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-Type="<T>">
     * This class prints a two dimensional {@code <T>}-array to a {@code String}.
     * 
     * @param <T> The type used by the {@code T[][]}-Array.  The {@code 'toString'}
     * parameter / function-pointer also must accept this type.
     * 
     * @param tArr           <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="TArr2D")
    public static <T> String toCSV(
            T[][] tArr, IntIntTFunc<? super T, String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return TArr2D.toCSV
            (tArr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // One Dimensional Primitive Arrays
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(byte[], int, int, IntByteFunction, Integer)}
     */
    @LinkJavaSource(handle="Byte1D")
    public static String toCSV
        (byte[] arr, IntByteFunction<String> toString, Integer maxLength)
    { return Byte1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=byte DATA-Lambda=IntByteFunction DATA-VarName=b>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code byte}.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Byte1D")
    public static String toCSV
        (byte[] arr, int sPos, int ePos, IntByteFunction<String> toString, Integer maxLength)
    { return Byte1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(short[], int, int, IntShortFunction, Integer)}
     */
    @LinkJavaSource(handle="Short1D")
    public static String toCSV
        (short[] arr, IntShortFunction<String> toString, Integer maxLength)
    { return Short1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=short DATA-Lambda=IntShortFunction DATA-VarName=s>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code short}-integers.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Short1D")
    public static String toCSV
        (short[] arr, int sPos, int ePos, IntShortFunction<String> toString, Integer maxLength)
    { return Short1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(int[], int, int, BiIntFunction, Integer)}
     */
    @LinkJavaSource(handle="Int1D")
    public static String toCSV
        (int[] arr, BiIntFunction<String> toString, Integer maxLength)
    { return Int1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=int DATA-Lambda=BiIntFunction DATA-VarName=j>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of integers.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Int1D")
    public static String toCSV
        (int[] arr, int sPos, int ePos, BiIntFunction<String> toString, Integer maxLength)
    { return Int1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(long[], int, int, IntLongFunction, Integer)}
     */
    @LinkJavaSource(handle="Long1D")
    public static String toCSV
        (long[] arr, IntLongFunction<String> toString, Integer maxLength)
    { return Long1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=long DATA-Lambda=IntLongFunction DATA-VarName=l>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code long}-integers.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Long1D")
    public static String toCSV
        (long[] arr, int sPos, int ePos, IntLongFunction<String> toString, Integer maxLength)
    { return Long1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(float[], int, int, IntFloatFunction, Integer)}
     */
    @LinkJavaSource(handle="Float1D")
    public static String toCSV
        (float[] arr, IntFloatFunction<String> toString, Integer maxLength)
    { return Float1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=float DATA-Lambda=IntFloatFunction DATA-VarName=f>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code float}.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Float1D")
    public static String toCSV
        (float[] arr, int sPos, int ePos, IntFloatFunction<String> toString, Integer maxLength)
    { return Float1D.toCSV(arr, sPos, ePos, toString, maxLength); }
    
    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(double[], int, int, IntDoubleFunction, Integer)}
     */
    @LinkJavaSource(handle="Double1D")
    public static String toCSV
        (double[] arr, IntDoubleFunction<String> toString, Integer maxLength)
    { return Double1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=double DATA-Lambda=IntDoubleFunction DATA-VarName=d>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code double}.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=numbers>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Double1D")
    public static String toCSV
        (double[] arr, int sPos, int ePos, IntDoubleFunction<String> toString, Integer maxLength)
    { return Double1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(boolean[], int, int, IntBoolFunction, Integer)}
     */
    @LinkJavaSource(handle="Boolean1D")
    public static String toCSV
        (boolean[] arr, IntBoolFunction<String> toString, Integer maxLength)
    { return Boolean1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=boolean DATA-Lambda=IntBoolFunction DATA-VarName=b>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code boolean}.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=booleans>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Boolean1D")
    public static String toCSV
        (boolean[] arr, int sPos, int ePos, IntBoolFunction<String> toString, Integer maxLength)
    { return Boolean1D.toCSV(arr, sPos, ePos, toString, maxLength); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toCSV(char[], int, int, IntCharFunction, Integer)}
     */
    @LinkJavaSource(handle="Char1D")
    public static String toCSV
        (char[] arr, IntCharFunction<String> toString, Integer maxLength)
    { return Char1D.toCSV(arr, 0, -1, toString, maxLength); }

    /**
     * <EMBED CLASS=defs DATA-ArrType=char DATA-Lambda=IntCharFunction DATA-VarName=c>
     * <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAIN_DESC>
     * 
     * @param arr       Any array of {@code boolean}.
     * @param sPos      <EMBED CLASS='external-html' DATA-FILE-ID=SPOSARRAY>
     * @param ePos      <EMBED CLASS='external-html' DATA-FILE-ID=EPOSARRAY>
     * @param toString  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TO_STRING DATA-word=characters>
     * @param maxLength <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN>
     * @return          <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_RETURN>
     * 
     * @throws ArrayIndexOutOfBoundsException <EMBED CLASS='external-html' DATA-FILE-ID=AIOOB_EX>
     * @throws NullPointerException           If {@code 'toString'} returns a null value.
     */
    @LinkJavaSource(handle="Char1D")
    public static String toCSV
        (char[] arr, int sPos, int ePos, IntCharFunction<String> toString, Integer maxLength)
    { return Char1D.toCSV(arr, sPos, ePos, toString, maxLength); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Two Dimensional Primitive Arrays
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-Type=byte>
     * This class prints a two dimensional {@code byte}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Byte2D")
    public static String toCSV(
            byte[][] arr, IntIntByteFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Byte2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=short>
     * This class prints a two dimensional {@code short}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Short2D")
    public static String toCSV(
            short[][] arr, IntIntShortFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Short2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=int>
     * This class prints a two dimensional {@code int}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Int2D")
    public static String toCSV(
            int[][] arr, TriIntFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Int2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=long>
     * This class prints a two dimensional {@code long}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Long2D")
    public static String toCSV(
            long[][] arr, IntIntLongFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Long2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=float>
     * This class prints a two dimensional {@code float}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Float2D")
    public static String toCSV(
            float[][] arr, IntIntFloatFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Float2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=double>
     * This class prints a two dimensional {@code double}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Double2D")
    public static String toCSV(
            double[][] arr, IntIntDoubleFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Double2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=char>
     * This class prints a two dimensional {@code char}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Char2D")
    public static String toCSV(
            char[][] arr, IntIntCharFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
       return Char2D.toCSV
           (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }

    /**
     * <EMBED CLASS=defs DATA-Type=boolean>
     * This class prints a two dimensional {@code boolean}-array to a {@code String}.
     * 
     * @param arr            <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_ARR_2D>
     * @param toString       <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_TSTR_2DARR>
     * @param keepRow        <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SUB_PRED>
     * @param separateLines  <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_SEPL_LINE>
     * @param maxLengthInner <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAX_LEN_IN>
     * @param maxLengthOuter <EMBED CLASS='external-html' DATA-FILE-ID=SCSV_MAXLEN_OUT>
     * @return               A printed version of this two-dimensional array.
     * 
     * @throws NullPointerException If the {@code 'toString'} method is non-null, but returns a
     * null value.
     * 
     * @throws IllegalArgumentException If {@code 'maxLengthInner'} is less than {@code '7'}.
     */
    @LinkJavaSource(handle="Boolean2D")
    public static String toCSV(
            boolean[][] arr, IntIntBoolFunc<String> toString, IntPredicate keepRow,
            boolean separateLines, Integer maxLengthInner, Integer maxLengthOuter
        )
    {
        return Boolean2D.toCSV
            (arr, toString, keepRow, separateLines, maxLengthInner, maxLengthOuter);
    }
}