package Torello.Java.JSON;

import javax.json.*; // For JavaDoc links

/**
 * Exception-Flags that may be passed to the {@code ReadJSON} methods which accept a
 * {@code 'FLAGS'} parameter.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>FLAG PRECEDENCE:</B>
 * 
 * <BR />If a user actually has multiple masks for the same error case, class
 * {@link ReadJSON} has an internal precedence / priority used for obeying the user-provided
 * flag-masks.  The flags that handle "On Any" or "On All" are always obeyed last.  If the
 * user has provided error or exception specific flags, those always take precedence over
 * the "Any &amp; All" mask.
 * 
 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes
 * precedence</I> over {@link #RETURN_DEFVAL_ON_ANY_ALL}</B>
 * 
 * <BR /><BR />If a user has provided multiple masks for the same case, and both of those
 * masks are error or exception flags, then a 'null' return takes precedence over a 
 * default-value return.
 * 
 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes
 * precedence</I> over {@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B>
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>ROCKET-SCIENCE NOTE:</B>
 * <BR />The following code has been directly cut and pasted - <I>from one of the internal,
 * {@code protected} <B>{@code 'GET'}</B> methods</I> found in {@link RJInternal}.  It is the
 * code for handling an {@code 'ArrayIndexOutOfBoundsException'}.  (See below that the
 * <B STYLE='color: red;'>Flag Precedence</B> rules are pretty straight-forward - <I><B>and
 * certainly are not rocket-science!</B></I>).
 *
 * <BR ><DIV CLASS=SNIP>{@code
 * if (index >= ja.size())
 * {
 *     if ((FLAGS & RETURN_NULL_ON_IOB) != 0)          return null;
 *     if ((FLAGS & RETURN_DEFVAL_ON_IOB) != 0)        return defaultValue;
 *     if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
 *     if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;
 *
 *     ja.get(index); // Throw an IndexOutOfBoundsException
 * }
 * }</DIV>
 * 
 * <BR /><BR />The complete set of handlers for these flags may be viewed inside the
 * exception-handler methods in class <B>{@link RJInternal}</B>.
 * 
 * <BR /><BR />The flag-handlers for the <B>{@link RJArrIntoPrimArray}</B> and
 * <B>{@link RJArrDimN}</B> classes are available for viewing (but buried) inside that
 * class.  To see those flag-handlers / exception-case-handlers, simply click the 
 * <B><CODE>HILITED</CODE></B> button in the Navigation Bar there (or the
 * <CODE><B>View Here:</B></CODE> link on that page).
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Java Bit-Wise Logic Syntax:</B>
 * 
 * <BR />As a simple reminder for how to "glue" together several flags, the following (simple)
 * bit-wise operator allows the programmer to place several flags inside of a single integer:
 * 
 * <DIV CLASS=LOC>{@code 
 * int myFlags = RETURN_DEFVAL_ON_ANY_ALL | RETURN_PARSE_ON_STR | RETURN_JAPPROX_ON_AEX;
 * }</DIV>
 * 
 * <BR />The above flags-integer would guarantee that any / all <B>{@link JsonString}</B> elements
 * found which are intended to be represented as numbers are parsed into numbers.  It would
 * furthermore use the standard JDK "rounding process" for numbers that will not fit into their
 * desired type.
 * 
 * <BR /><BR />Any other exceptions that might occur while processing a Json Element will produce
 * whatever Default-Value has been passed to the method parameter {@code defaultValue}.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=NULL_FLAGS_PRIM>
 */
@Torello.JavaDoc.StaticFunctional
public class JFlag
{
    private JFlag() { }

    /**
     * This is a "Primary Flag" that indicates the reader should always
     * <B STYLE='color: red;'>return null</B> for any exception-throw or error case that could
     * possibly occur. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
     * 
     * <BR />When this flag is set, it always has the lowest precedence compared to all other
     * flags.  Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were
     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the
     * user-provided default-value would be returned, rather than null.
     * 
     * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always
     * be returned, rather than the default-value.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     */
    public static final int RETURN_NULL_ON_ANY_ALL = 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_ANY_ALL}</B> */
    public static final int RN_AA = RETURN_NULL_ON_ANY_ALL;

    /**
     * This is a "Primary Flag" that indicates the reader should always return the
     * user-provided default-value for any exception-throw or error case that could possibly
     * occur.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
     * 
     * <BR />When this flag is set, it always has the lowest precedence compared to all other
     * flags.  Specifically, if this flag, and the flag {@link #RETURN_NULL_ON_AEX} were
     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, null
     * would be returned, rather than the user-provided default-value.
     * 
     * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always
     * be returned, rather than the default-value.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     */
    public static final int RETURN_DEFVAL_ON_ANY_ALL = RN_AA << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_ANY_ALL}</B> */
    public static final int RD_AA = RETURN_DEFVAL_ON_ANY_ALL;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B> if an
     * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown.
     * This flag-mask is only useful with methods that accept <B>{@link JsonArray}</B> and
     * {@code 'index'} parameters. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_IOB}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     */
    public static final int RETURN_NULL_ON_IOB = RD_AA << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_IOB}</B> */
    public static final int RN_IOB = RETURN_NULL_ON_IOB;

    /**
     * Instructs a get method to return the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an
     * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown.
     * This flag-mask is only useful to methods which accept <B>{@link JsonArray}</B> and
     * {@code 'index'} parameters.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_IOB}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     */
    public static final int RETURN_DEFVAL_ON_IOB = RN_IOB << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_IOB}</B> */
    public static final int RD_IOB = RETURN_DEFVAL_ON_IOB;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B> when a specified property
     * <I>isn't actually present in a <B>{@link JsonObject}</B></I>.  This flag-mask is only useful
     * to methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_M}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     * 
     * @see JsonPropMissingException
     */
    public static final int RETURN_NULL_ON_MISSING = RD_IOB << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_MISSING}</B> */
    public static final int RN_M = RETURN_NULL_ON_MISSING;

    /**
     * Instructs a get method to return a user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> when a specified property <I> isn't
     * actually present in a <B>{@link JsonObject}</B></I>.  This flag-mask is only useful to
     * methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_M}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     * 
     * @see JsonPropMissingException
     */
    public static final int RETURN_DEFVAL_ON_MISSING = RN_M << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_MISSING}</B> */
    public static final int RD_M = RETURN_DEFVAL_ON_MISSING;

    /**
     * Instructs a get method to return <B STYLE='color: red;'>Java-Null</B> whenever a
     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains
     * <B STYLE='color: red;'>Json-Null</B>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_N}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonNullArrException
     * @see JsonNullObjException
     * @see JsonNullPrimitiveArrException
     * @see JsonNullPrimitiveObjException
     */
    public static final int RETURN_NULL_ON_NULL = RD_M << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_NULL}</B> */
    public static final int RN_N = RETURN_NULL_ON_NULL;

    /**
     * Instructs a get method to return a user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a <B>{@link JsonObject}</B>
     * property or <B>{@link JsonArray}</B> index contains <B STYLE='color: red;'>Json-Null</B>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_N}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonNullArrException
     * @see JsonNullObjException
     * @see JsonNullPrimitiveArrException
     * @see JsonNullPrimitiveObjException
     */
    public static final int RETURN_DEFVAL_ON_NULL = RN_N << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_NULL}</B> */
    public static final int RD_N = RETURN_DEFVAL_ON_NULL;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B> if an
     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_AEX}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonArithmeticArrException
     * @see JsonArithmeticObjException
     */
    public static final int RETURN_NULL_ON_AEX = RD_N << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_AEX}</B> */
    public static final int RN_AEX = RETURN_NULL_ON_AEX;

    /**
     * Instructs a get method to return the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an
     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_AEX}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonArithmeticArrException
     * @see JsonArithmeticObjException
     */
    public static final int RETURN_DEFVAL_ON_AEX = RN_AEX << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_AEX}</B> */
    public static final int RD_AEX = RETURN_DEFVAL_ON_AEX;

    /**
     * Instructs a get method to use a Standard Java Alternative / Rounding Method if an
     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown.  
     * 
     * <EMBED CLASS='external-html' DATA-FILE-ID=JRJF_APPROX>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RJA_AEX}</B> is an abbreviated but identical value that may
     * be used if brevity is a higher priority than readability. 
     * 
     * @see JsonArithmeticArrException
     * @see JsonArithmeticObjException
     */
    public static final int RETURN_JAPPROX_ON_AEX = RD_AEX << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_JAPPROX_ON_AEX}</B> */
    public static final int RJA_AEX = RETURN_JAPPROX_ON_AEX;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a
     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index does not contain the
     * expected <B>Json-Type</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_WT}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonTypeArrException
     * @see JsonTypeObjException
     */
    public static final int RETURN_NULL_ON_WRONG_JSONTYPE = RJA_AEX << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_WRONG_JSONTYPE}</B> */
    public static final int RN_WT = RETURN_NULL_ON_WRONG_JSONTYPE;

    /**
     * Instructs a get method to return the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B>
     * property or <B>{@link JsonArray}</B> index does not contain the expected <B>Json-Type</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_WT}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * @see JsonTypeArrException
     * @see JsonTypeObjException
     */
    public static final int RETURN_DEFVAL_ON_WRONG_JSONTYPE = RN_WT << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B> */
    public static final int RD_WT = RETURN_DEFVAL_ON_WRONG_JSONTYPE;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a
     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains a
     * <B STYLE='color: red;'>zero-length</B> <B>{@link JsonString}</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_ZLS}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     */
    public static final int RETURN_NULL_ON_0LEN_STR = RD_WT << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_0LEN_STR}</B> */
    public static final int RN_ZLS = RETURN_NULL_ON_0LEN_STR;

    /**
     * Instructs a get method to return the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B>
     * property or <B>{@link JsonArray}</B> index contains a <B STYLE='color: red;'>zero-length</B>
     * <B>{@link JsonString}</B> 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_ZLS}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability.
     */
    public static final int RETURN_DEFVAL_ON_0LEN_STR = RN_ZLS << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_0LEN_STR}</B> */
    public static final int RD_ZLS = RETURN_DEFVAL_ON_0LEN_STR;

    /**
     * Instructs a get method to <B STYLE='color: red;'>return null</B>  in cases where the
     * user-provided {@code 'parser'} function has thrown an exception.
     * 
     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_SPEX}</B> is an abbreviated but identical value that may
     * be used if brevity is a higher priority than readability. 
     * 
     * @see JsonStrParseArrException
     * @see JsonStrParseObjException
     */
    public static final int RETURN_NULL_ON_SPEX = RD_ZLS << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_SPEX}</B> */
    public static final int RN_SPEX = RETURN_NULL_ON_SPEX;

    /**
     * Instructs a get method to return the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where the user-provided
     * {@code 'parser'} function has thrown an exception. 
     * 
     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_SPEX}</B> is an abbreviated but identical value that may
     * be used if brevity is a higher priority than readability. 
     * 
     * @see JsonStrParseArrException
     * @see JsonStrParseObjException
     */
    public static final int RETURN_DEFVAL_ON_SPEX = RN_SPEX << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_SPEX}</B> */
    public static final int RD_SPEX = RETURN_DEFVAL_ON_SPEX;


    // ********************************************************************************************
    // ********************************************************************************************
    // RJArrIntoPrimArray-Specific Flags
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is a "Primary Flag" that indicates the reader should always
     * <B STYLE='color: red;'>skip</B> any array-entry for any exception-throw or error case that
     * could possibly occur. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
     * 
     * <BR />When this flag is set, it always has the lowest precedence compared to all other
     * flags.  Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were
     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the
     * user-provided default-value would be placed into the output, rather than being skipped.
     * 
     * <BR /><BR />If both flag {@link #S_AA} and {@link #RN_AA} are set, 'null' will always
     * be placed into the output, before skipping the array-index, or using the default-value.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_AA}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     */
    public static final int SKIP_ON_ANY_ALL = RD_SPEX << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_ANY_ALL}</B> */
    public static final int S_AA = SKIP_ON_ANY_ALL;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array
     * element, if-and-when a <B>{@link JsonArray}</B> index contain a <B>Json-Null</B>.
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_N}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_NULL = S_AA << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_NULL}</B> */
    public static final int S_N = SKIP_ON_NULL;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array
     * element, if-and-when if an <B STYLE='color: red;'>{@code ArithmeticException}</B> would
     * otherwise be thrown. 
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_AEX}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_AEX = S_N << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_AEX}</B> */
    public static final int S_AEX = SKIP_ON_AEX;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>parse</B> an array
     * element into a number, if-and-when a <B>{@link JsonString}</B> is encountered.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RP_S}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.
     */
    public static final int RETURN_PARSE_ON_STR = S_AEX << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_PARSE_ON_STR}</B> */
    public static final int RP_S = RETURN_PARSE_ON_STR;

    /**
     * Instructs a boxed-stream builder method to insert <B STYLE='color: red;'>Java-Null</B> 
     * into the boxed-stream whenever a <B>{@link JsonArray}</B> index contains a
     * {@link JsonString}.
     * 
     * <BR /><BR />This flag is ignored if passed to a primitive-stream builder method.  A 
     * primitive-stream (and its associated builder) will not accept nulls.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RN_S}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.
     */
    public static final int RETURN_NULL_ON_STR = RP_S << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_STR}</B> */
    public static final int RN_S = RETURN_NULL_ON_STR;

    /**
     * Instructs an array / stream builder method to insert the user-provided
     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a {@link JsonString} is
     * encountered at a particular index inside a {@link JsonArray}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RD_S}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.
     */
    public static final int RETURN_DEFVAL_ON_STR = RN_S << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_STR}</B> */
    public static final int RD_S = RETURN_DEFVAL_ON_STR;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
     * {@link JsonArray} index-locations that contain a {@link JsonString}.
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_S}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_STR = RD_S << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_STR}</B> */
    public static final int S_S = SKIP_ON_STR;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
     * {@link JsonArray} index-locations that contain a <B STYLE='color: red'>Zero-Length</B>
     * {@link JsonString}.
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_ZLS}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_0LEN_STR = S_S << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_0LEN_STR}</B> */
    public static final int S_ZLS = SKIP_ON_0LEN_STR;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
     * {@link JsonArray} index-locations that contain a {@link JsonString} that, when parsed,
     * generate any parse-exceptions, such as {@code NumberFormatException}.
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_SPEX}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_SPEX = S_ZLS << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_SPEX}</B> */
    public static final int S_SPEX = SKIP_ON_SPEX;

    /**
     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
     * {@link JsonArray} index-locations that contain an inapplicable
     * <B STYLE='color: red;'>Json-Type</B> - such as {@code JsonValue.TRUE},
     * {@code JsonValue.FALSE}, {@code JsonObject}, a nested {@code JsonArray} etc...
     * 
     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
     * by the number of skipped-indices</I>.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_WT}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
     * be applied to array-processing methods.
     */
    public static final int SKIP_ON_WRONG_JSONTYPE = S_SPEX << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_WRONG_JSONTYPE}</B> */
    public static final int S_WT = SKIP_ON_WRONG_JSONTYPE;


    // ********************************************************************************************
    // ********************************************************************************************
    // ADDITIONAL: RJArrIntoPrimArray-Specific Flags
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Instructs the {@code Stream<String>} (array/stream) builder method to invoke 
     * {@link JsonValue#toString} whenever a type other than {@link JsonString} is found in an
     * array position.  This flag is only applicable when converting a {@link JsonArray} into a
     * {@code String[]}-Array.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #RTS_WT}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Specific Method Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
     * useful in invocations of method {@link RJArrIntoStream#strArr}.
     */
    public static final int RETURN_TOSTRING_ON_WRONGTYPE = S_WT << 1;

    /** Identical to flag-mask field <B>{@link #RETURN_TOSTRING_ON_WRONGTYPE}</B> */
    public static final int RTS_WT = RETURN_TOSTRING_ON_WRONGTYPE;


    // ********************************************************************************************
    // ********************************************************************************************
    // ADDITIONAL: RJArrDimN Specific Flags
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Instructs the multi-dimensional array-builder method to place a null in an array when
     * it encounters a {@link JsonArray} element that is not a sub-array, but rather some other
     * non-null <B STYLE='color: red;'>Json-Type</B>  This flag is only applicable when converting
     * a {@link JsonArray} using one of the multi-dimensional array-processors in class
     * {@link RJArrDimN}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #IN_NSAT}</B> is an abbreviated but identical value that may
     * be used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in
     * {@link RJArrIntoPrimArray}.  It is only used in processing multi-dimensional arrays (by
     * class {@link RJArrDimN}).
     */
    public static final int INSERT_NULL_ON_NON_SUBARRAY_TYPE = RTS_WT << 1;

    /** Identical to flag-mask field <B>{@link #INSERT_NULL_ON_NON_SUBARRAY_TYPE}</B> */
    public static final int IN_NSAT = INSERT_NULL_ON_NON_SUBARRAY_TYPE;

    /**
     * Instructs the multi-dimensional array-builder method to skip the element when it encounters
     * a {@link JsonArray} element that is not a sub-array, but rather some other non-null
     * <B STYLE='color: red;'>Json-Type</B>  This flag is only applicable when converting
     * a {@link JsonArray} using one of the multi-dimensional array-processors in class
     * {@link RJArrDimN}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
     * 
     * <BR />The flag-mask <B>{@link #S_NSAT}</B> is an abbreviated but identical value that may be
     * used if brevity is a higher priority than readability. 
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B>
     * 
     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in
     * {@link RJArrIntoPrimArray}.  It is only used in processing multi-dimensional arrays (by
     * class {@link RJArrDimN}).
     */
    public static final int SKIP_ON_NON_SUBARRAY_TYPE = IN_NSAT << 1;

    /** Identical to flag-mask field <B>{@link #SKIP_ON_NON_SUBARRAY_TYPE}</B> */
    public static final int S_NSAT = SKIP_ON_NON_SUBARRAY_TYPE;

    /** 
     * These are eliminated / removed from any call to a method which returns either an array
     * of Java Primitives or a Java Primitive Stream.  These are also filtered from a call to class
     * that invokes a Java Primitive-Consumer
     * 
     * @see RJArrIntoPrimStream#intArr(JsonArray, int, int, ToIntFunction)
     * @see RJArrIntoPrimStream#longArr(JsonArray, long, int, ToLongFunction)
     * @see RJArrIntoPrimStream#doubleArr(JsonArray, double, int, ToDoubleFunction)
     * 
     * @see RJArrIntoPrimConsumer
     */
    public static final int NOT_ALLOWED_RET_NULL_MASKS = ~(RETURN_NULL_ON_ANY_ALL |
        RETURN_NULL_ON_AEX | RETURN_NULL_ON_NULL | RETURN_NULL_ON_SPEX | RETURN_NULL_ON_STR |
        RETURN_NULL_ON_0LEN_STR | RETURN_NULL_ON_WRONG_JSONTYPE | INSERT_NULL_ON_NON_SUBARRAY_TYPE);
}