001package Torello.Java.JSON;
002
003import javax.json.*; // For JavaDoc links
004
005/**
006 * Exception-Flags that may be passed to the {@code ReadJSON} methods which accept a
007 * {@code 'FLAGS'} parameter.
008 * 
009 * <BR /><BR /><B CLASS=JDDescLabel>FLAG PRECEDENCE:</B>
010 * 
011 * <BR />If a user actually has multiple masks for the same error case, class
012 * {@link ReadJSON} has an internal precedence / priority used for obeying the user-provided
013 * flag-masks.  The flags that handle "On Any" or "On All" are always obeyed last.  If the
014 * user has provided error or exception specific flags, those always take precedence over
015 * the "Any &amp; All" mask.
016 * 
017 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes
018 * precedence</I> over {@link #RETURN_DEFVAL_ON_ANY_ALL}</B>
019 * 
020 * <BR /><BR />If a user has provided multiple masks for the same case, and both of those
021 * masks are error or exception flags, then a 'null' return takes precedence over a 
022 * default-value return.
023 * 
024 * <BR /><BR /><B>SPECIFICALLY: {@link #RETURN_NULL_ON_WRONG_JSONTYPE} <I>takes
025 * precedence</I> over {@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B>
026 * 
027 * <BR /><BR /><B CLASS=JDDescLabel>ROCKET-SCIENCE NOTE:</B>
028 * <BR />The following code has been directly cut and pasted - <I>from one of the internal,
029 * {@code protected} <B>{@code 'GET'}</B> methods</I> found in {@link RJInternal}.  It is the
030 * code for handling an {@code 'ArrayIndexOutOfBoundsException'}.  (See below that the
031 * <B STYLE='color: red;'>Flag Precedence</B> rules are pretty straight-forward - <I><B>and
032 * certainly are not rocket-science!</B></I>).
033 *
034 * <BR ><DIV CLASS=SNIP>{@code
035 * if (index >= ja.size())
036 * {
037 *     if ((FLAGS & RETURN_NULL_ON_IOB) != 0)          return null;
038 *     if ((FLAGS & RETURN_DEFVAL_ON_IOB) != 0)        return defaultValue;
039 *     if ((FLAGS & RETURN_NULL_ON_ANY_ALL) != 0)      return null;
040 *     if ((FLAGS & RETURN_DEFVAL_ON_ANY_ALL) != 0)    return defaultValue;
041 *
042 *     ja.get(index); // Throw an IndexOutOfBoundsException
043 * }
044 * }</DIV>
045 * 
046 * <BR /><BR />The complete set of handlers for these flags may be viewed inside the
047 * exception-handler methods in class <B>{@link RJInternal}</B>.
048 * 
049 * <BR /><BR />The flag-handlers for the <B>{@link RJArrIntoPrimArray}</B> and
050 * <B>{@link RJArrDimN}</B> classes are available for viewing (but buried) inside that
051 * class.  To see those flag-handlers / exception-case-handlers, simply click the 
052 * <B><CODE>HILITED</CODE></B> button in the Navigation Bar there (or the
053 * <CODE><B>View Here:</B></CODE> link on that page).
054 * 
055 * <BR /><BR /><B CLASS=JDDescLabel>Java Bit-Wise Logic Syntax:</B>
056 * 
057 * <BR />As a simple reminder for how to "glue" together several flags, the following (simple)
058 * bit-wise operator allows the programmer to place several flags inside of a single integer:
059 * 
060 * <DIV CLASS=LOC>{@code 
061 * int myFlags = RETURN_DEFVAL_ON_ANY_ALL | RETURN_PARSE_ON_STR | RETURN_JAPPROX_ON_AEX;
062 * }</DIV>
063 * 
064 * <BR />The above flags-integer would guarantee that any / all <B>{@link JsonString}</B> elements
065 * found which are intended to be represented as numbers are parsed into numbers.  It would
066 * furthermore use the standard JDK "rounding process" for numbers that will not fit into their
067 * desired type.
068 * 
069 * <BR /><BR />Any other exceptions that might occur while processing a Json Element will produce
070 * whatever Default-Value has been passed to the method parameter {@code defaultValue}.
071 * 
072 * <EMBED CLASS='external-html' DATA-FILE-ID=NULL_FLAGS_PRIM>
073 */
074@Torello.JavaDoc.StaticFunctional
075public class JFlag
076{
077    private JFlag() { }
078
079    /**
080     * This is a "Primary Flag" that indicates the reader should always
081     * <B STYLE='color: red;'>return null</B> for any exception-throw or error case that could
082     * possibly occur. 
083     * 
084     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
085     * 
086     * <BR />When this flag is set, it always has the lowest precedence compared to all other
087     * flags.  Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were
088     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the
089     * user-provided default-value would be returned, rather than null.
090     * 
091     * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always
092     * be returned, rather than the default-value.
093     * 
094     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
095     * 
096     * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be
097     * used if brevity is a higher priority than readability. 
098     */
099    public static final int RETURN_NULL_ON_ANY_ALL = 1;
100
101    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_ANY_ALL}</B> */
102    public static final int RN_AA = RETURN_NULL_ON_ANY_ALL;
103
104    /**
105     * This is a "Primary Flag" that indicates the reader should always return the
106     * user-provided default-value for any exception-throw or error case that could possibly
107     * occur.
108     * 
109     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
110     * 
111     * <BR />When this flag is set, it always has the lowest precedence compared to all other
112     * flags.  Specifically, if this flag, and the flag {@link #RETURN_NULL_ON_AEX} were
113     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, null
114     * would be returned, rather than the user-provided default-value.
115     * 
116     * <BR /><BR />If both flag {@link #RN_AA} and {@link #RD_AA} are set, 'null' will always
117     * be returned, rather than the default-value.
118     * 
119     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
120     * 
121     * <BR />The flag-mask <B>{@link #RN_AA}</B> is an abbreviated but identical value that may be
122     * used if brevity is a higher priority than readability.
123     */
124    public static final int RETURN_DEFVAL_ON_ANY_ALL = RN_AA << 1;
125
126    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_ANY_ALL}</B> */
127    public static final int RD_AA = RETURN_DEFVAL_ON_ANY_ALL;
128
129    /**
130     * Instructs a get method to <B STYLE='color: red;'>return null</B> if an
131     * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown.
132     * This flag-mask is only useful with methods that accept <B>{@link JsonArray}</B> and
133     * {@code 'index'} parameters. 
134     * 
135     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
136     * 
137     * <BR />The flag-mask <B>{@link #RN_IOB}</B> is an abbreviated but identical value that may be
138     * used if brevity is a higher priority than readability.
139     */
140    public static final int RETURN_NULL_ON_IOB = RD_AA << 1;
141
142    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_IOB}</B> */
143    public static final int RN_IOB = RETURN_NULL_ON_IOB;
144
145    /**
146     * Instructs a get method to return the user-provided
147     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an
148     * <B STYLE='color: red;'>{@code IndexOutOfBoundsException}</B> would otherwise be thrown.
149     * This flag-mask is only useful to methods which accept <B>{@link JsonArray}</B> and
150     * {@code 'index'} parameters.
151     * 
152     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
153     * 
154     * <BR />The flag-mask <B>{@link #RD_IOB}</B> is an abbreviated but identical value that may be
155     * used if brevity is a higher priority than readability.
156     */
157    public static final int RETURN_DEFVAL_ON_IOB = RN_IOB << 1;
158
159    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_IOB}</B> */
160    public static final int RD_IOB = RETURN_DEFVAL_ON_IOB;
161
162    /**
163     * Instructs a get method to <B STYLE='color: red;'>return null</B> when a specified property
164     * <I>isn't actually present in a <B>{@link JsonObject}</B></I>.  This flag-mask is only useful
165     * to methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter.
166     * 
167     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
168     * 
169     * <BR />The flag-mask <B>{@link #RN_M}</B> is an abbreviated but identical value that may be
170     * used if brevity is a higher priority than readability.
171     * 
172     * @see JsonPropMissingException
173     */
174    public static final int RETURN_NULL_ON_MISSING = RD_IOB << 1;
175
176    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_MISSING}</B> */
177    public static final int RN_M = RETURN_NULL_ON_MISSING;
178
179    /**
180     * Instructs a get method to return a user-provided
181     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> when a specified property <I> isn't
182     * actually present in a <B>{@link JsonObject}</B></I>.  This flag-mask is only useful to
183     * methods that accept a {@code 'propertyName'} and {@code JsonObject} parameter.
184     * 
185     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
186     * 
187     * <BR />The flag-mask <B>{@link #RD_M}</B> is an abbreviated but identical value that may be
188     * used if brevity is a higher priority than readability.
189     * 
190     * @see JsonPropMissingException
191     */
192    public static final int RETURN_DEFVAL_ON_MISSING = RN_M << 1;
193
194    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_MISSING}</B> */
195    public static final int RD_M = RETURN_DEFVAL_ON_MISSING;
196
197    /**
198     * Instructs a get method to return <B STYLE='color: red;'>Java-Null</B> whenever a
199     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains
200     * <B STYLE='color: red;'>Json-Null</B>.
201     * 
202     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
203     * 
204     * <BR />The flag-mask <B>{@link #RN_N}</B> is an abbreviated but identical value that may be
205     * used if brevity is a higher priority than readability. 
206     * 
207     * @see JsonNullArrException
208     * @see JsonNullObjException
209     * @see JsonNullPrimitiveArrException
210     * @see JsonNullPrimitiveObjException
211     */
212    public static final int RETURN_NULL_ON_NULL = RD_M << 1;
213
214    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_NULL}</B> */
215    public static final int RN_N = RETURN_NULL_ON_NULL;
216
217    /**
218     * Instructs a get method to return a user-provided
219     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a <B>{@link JsonObject}</B>
220     * property or <B>{@link JsonArray}</B> index contains <B STYLE='color: red;'>Json-Null</B>.
221     * 
222     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
223     * 
224     * <BR />The flag-mask <B>{@link #RD_N}</B> is an abbreviated but identical value that may be
225     * used if brevity is a higher priority than readability. 
226     * 
227     * @see JsonNullArrException
228     * @see JsonNullObjException
229     * @see JsonNullPrimitiveArrException
230     * @see JsonNullPrimitiveObjException
231     */
232    public static final int RETURN_DEFVAL_ON_NULL = RN_N << 1;
233
234    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_NULL}</B> */
235    public static final int RD_N = RETURN_DEFVAL_ON_NULL;
236
237    /**
238     * Instructs a get method to <B STYLE='color: red;'>return null</B> if an
239     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown.
240     * 
241     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
242     * 
243     * <BR />The flag-mask <B>{@link #RN_AEX}</B> is an abbreviated but identical value that may be
244     * used if brevity is a higher priority than readability. 
245     * 
246     * @see JsonArithmeticArrException
247     * @see JsonArithmeticObjException
248     */
249    public static final int RETURN_NULL_ON_AEX = RD_N << 1;
250
251    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_AEX}</B> */
252    public static final int RN_AEX = RETURN_NULL_ON_AEX;
253
254    /**
255     * Instructs a get method to return the user-provided
256     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> if an
257     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown. 
258     * 
259     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
260     * 
261     * <BR />The flag-mask <B>{@link #RD_AEX}</B> is an abbreviated but identical value that may be
262     * used if brevity is a higher priority than readability. 
263     * 
264     * @see JsonArithmeticArrException
265     * @see JsonArithmeticObjException
266     */
267    public static final int RETURN_DEFVAL_ON_AEX = RN_AEX << 1;
268
269    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_AEX}</B> */
270    public static final int RD_AEX = RETURN_DEFVAL_ON_AEX;
271
272    /**
273     * Instructs a get method to use a Standard Java Alternative / Rounding Method if an
274     * <B STYLE='color: red;'>{@code ArithmeticException}</B> would otherwise be thrown.  
275     * 
276     * <EMBED CLASS='external-html' DATA-FILE-ID=JRJF_APPROX>
277     * 
278     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
279     * 
280     * <BR />The flag-mask <B>{@link #RJA_AEX}</B> is an abbreviated but identical value that may
281     * be used if brevity is a higher priority than readability. 
282     * 
283     * @see JsonArithmeticArrException
284     * @see JsonArithmeticObjException
285     */
286    public static final int RETURN_JAPPROX_ON_AEX = RD_AEX << 1;
287
288    /** Identical to flag-mask field <B>{@link #RETURN_JAPPROX_ON_AEX}</B> */
289    public static final int RJA_AEX = RETURN_JAPPROX_ON_AEX;
290
291    /**
292     * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a
293     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index does not contain the
294     * expected <B>Json-Type</B>
295     * 
296     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
297     * 
298     * <BR />The flag-mask <B>{@link #RN_WT}</B> is an abbreviated but identical value that may be
299     * used if brevity is a higher priority than readability. 
300     * 
301     * @see JsonTypeArrException
302     * @see JsonTypeObjException
303     */
304    public static final int RETURN_NULL_ON_WRONG_JSONTYPE = RJA_AEX << 1;
305
306    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_WRONG_JSONTYPE}</B> */
307    public static final int RN_WT = RETURN_NULL_ON_WRONG_JSONTYPE;
308
309    /**
310     * Instructs a get method to return the user-provided
311     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B>
312     * property or <B>{@link JsonArray}</B> index does not contain the expected <B>Json-Type</B>
313     * 
314     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
315     * 
316     * <BR />The flag-mask <B>{@link #RD_WT}</B> is an abbreviated but identical value that may be
317     * used if brevity is a higher priority than readability. 
318     * 
319     * @see JsonTypeArrException
320     * @see JsonTypeObjException
321     */
322    public static final int RETURN_DEFVAL_ON_WRONG_JSONTYPE = RN_WT << 1;
323
324    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_WRONG_JSONTYPE}</B> */
325    public static final int RD_WT = RETURN_DEFVAL_ON_WRONG_JSONTYPE;
326
327    /**
328     * Instructs a get method to <B STYLE='color: red;'>return null</B> in cases where a
329     * <B>{@link JsonObject}</B> property or <B>{@link JsonArray}</B> index contains a
330     * <B STYLE='color: red;'>zero-length</B> <B>{@link JsonString}</B>
331     * 
332     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
333     * 
334     * <BR />The flag-mask <B>{@link #RN_ZLS}</B> is an abbreviated but identical value that may be
335     * used if brevity is a higher priority than readability.
336     */
337    public static final int RETURN_NULL_ON_0LEN_STR = RD_WT << 1;
338
339    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_0LEN_STR}</B> */
340    public static final int RN_ZLS = RETURN_NULL_ON_0LEN_STR;
341
342    /**
343     * Instructs a get method to return the user-provided
344     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where a <B>{@link JsonObject}</B>
345     * property or <B>{@link JsonArray}</B> index contains a <B STYLE='color: red;'>zero-length</B>
346     * <B>{@link JsonString}</B> 
347     * 
348     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
349     * 
350     * <BR />The flag-mask <B>{@link #RD_ZLS}</B> is an abbreviated but identical value that may be
351     * used if brevity is a higher priority than readability.
352     */
353    public static final int RETURN_DEFVAL_ON_0LEN_STR = RN_ZLS << 1;
354
355    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_0LEN_STR}</B> */
356    public static final int RD_ZLS = RETURN_DEFVAL_ON_0LEN_STR;
357
358    /**
359     * Instructs a get method to <B STYLE='color: red;'>return null</B>  in cases where the
360     * user-provided {@code 'parser'} function has thrown an exception.
361     * 
362     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
363     * 
364     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
365     * 
366     * <BR />The flag-mask <B>{@link #RN_SPEX}</B> is an abbreviated but identical value that may
367     * be used if brevity is a higher priority than readability. 
368     * 
369     * @see JsonStrParseArrException
370     * @see JsonStrParseObjException
371     */
372    public static final int RETURN_NULL_ON_SPEX = RD_ZLS << 1;
373
374    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_SPEX}</B> */
375    public static final int RN_SPEX = RETURN_NULL_ON_SPEX;
376
377    /**
378     * Instructs a get method to return the user-provided
379     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> in cases where the user-provided
380     * {@code 'parser'} function has thrown an exception. 
381     * 
382     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
383     * 
384     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
385     * 
386     * <BR />The flag-mask <B>{@link #RD_SPEX}</B> is an abbreviated but identical value that may
387     * be used if brevity is a higher priority than readability. 
388     * 
389     * @see JsonStrParseArrException
390     * @see JsonStrParseObjException
391     */
392    public static final int RETURN_DEFVAL_ON_SPEX = RN_SPEX << 1;
393
394    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_SPEX}</B> */
395    public static final int RD_SPEX = RETURN_DEFVAL_ON_SPEX;
396
397
398    // ********************************************************************************************
399    // ********************************************************************************************
400    // RJArrIntoPrimArray-Specific Flags
401    // ********************************************************************************************
402    // ********************************************************************************************
403
404
405    /**
406     * This is a "Primary Flag" that indicates the reader should always
407     * <B STYLE='color: red;'>skip</B> any array-entry for any exception-throw or error case that
408     * could possibly occur. 
409     * 
410     * <BR /><BR /><B CLASS=JDDescLabel>Flag Precedence:</B>
411     * 
412     * <BR />When this flag is set, it always has the lowest precedence compared to all other
413     * flags.  Specifically, if this flag, and the flag {@link #RETURN_DEFVAL_ON_AEX} were
414     * <B><I>both set</I></B>, and an {@code ArithmeticException} were going to be thrown, the
415     * user-provided default-value would be placed into the output, rather than being skipped.
416     * 
417     * <BR /><BR />If both flag {@link #S_AA} and {@link #RN_AA} are set, 'null' will always
418     * be placed into the output, before skipping the array-index, or using the default-value.
419     * 
420     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
421     * 
422     * <BR />The flag-mask <B>{@link #S_AA}</B> is an abbreviated but identical value that may be
423     * used if brevity is a higher priority than readability. 
424     */
425    public static final int SKIP_ON_ANY_ALL = RD_SPEX << 1;
426
427    /** Identical to flag-mask field <B>{@link #SKIP_ON_ANY_ALL}</B> */
428    public static final int S_AA = SKIP_ON_ANY_ALL;
429
430    /**
431     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array
432     * element, if-and-when a <B>{@link JsonArray}</B> index contain a <B>Json-Null</B>.
433     * 
434     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
435     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
436     * by the number of skipped-indices</I>.
437     * 
438     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
439     * 
440     * <BR />The flag-mask <B>{@link #S_N}</B> is an abbreviated but identical value that may be
441     * used if brevity is a higher priority than readability. 
442     * 
443     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
444     * 
445     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
446     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
447     * be applied to array-processing methods.
448     */
449    public static final int SKIP_ON_NULL = S_AA << 1;
450
451    /** Identical to flag-mask field <B>{@link #SKIP_ON_NULL}</B> */
452    public static final int S_N = SKIP_ON_NULL;
453
454    /**
455     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> an array
456     * element, if-and-when if an <B STYLE='color: red;'>{@code ArithmeticException}</B> would
457     * otherwise be thrown. 
458     * 
459     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
460     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
461     * by the number of skipped-indices</I>.
462     * 
463     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
464     * 
465     * <BR />The flag-mask <B>{@link #S_AEX}</B> is an abbreviated but identical value that may be
466     * used if brevity is a higher priority than readability. 
467     * 
468     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
469     * 
470     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
471     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
472     * be applied to array-processing methods.
473     */
474    public static final int SKIP_ON_AEX = S_N << 1;
475
476    /** Identical to flag-mask field <B>{@link #SKIP_ON_AEX}</B> */
477    public static final int S_AEX = SKIP_ON_AEX;
478
479    /**
480     * Instructs an array / stream builder method to <B STYLE='color: red;'>parse</B> an array
481     * element into a number, if-and-when a <B>{@link JsonString}</B> is encountered.
482     * 
483     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
484     * 
485     * <BR />The flag-mask <B>{@link #RP_S}</B> is an abbreviated but identical value that may be
486     * used if brevity is a higher priority than readability. 
487     * 
488     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
489     * 
490     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
491     * useful in {@link RJArrIntoPrimArray}.
492     */
493    public static final int RETURN_PARSE_ON_STR = S_AEX << 1;
494
495    /** Identical to flag-mask field <B>{@link #RETURN_PARSE_ON_STR}</B> */
496    public static final int RP_S = RETURN_PARSE_ON_STR;
497
498    /**
499     * Instructs a boxed-stream builder method to insert <B STYLE='color: red;'>Java-Null</B> 
500     * into the boxed-stream whenever a <B>{@link JsonArray}</B> index contains a
501     * {@link JsonString}.
502     * 
503     * <BR /><BR />This flag is ignored if passed to a primitive-stream builder method.  A 
504     * primitive-stream (and its associated builder) will not accept nulls.
505     * 
506     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
507     * 
508     * <BR />The flag-mask <B>{@link #RN_S}</B> is an abbreviated but identical value that may be
509     * used if brevity is a higher priority than readability. 
510     * 
511     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
512     * 
513     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
514     * useful in {@link RJArrIntoPrimArray}.
515     */
516    public static final int RETURN_NULL_ON_STR = RP_S << 1;
517
518    /** Identical to flag-mask field <B>{@link #RETURN_NULL_ON_STR}</B> */
519    public static final int RN_S = RETURN_NULL_ON_STR;
520
521    /**
522     * Instructs an array / stream builder method to insert the user-provided
523     * <B STYLE='color: red;'>{@code 'defaultValue'}</B> whenever a {@link JsonString} is
524     * encountered at a particular index inside a {@link JsonArray}.
525     * 
526     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
527     * 
528     * <BR />The flag-mask <B>{@link #RD_S}</B> is an abbreviated but identical value that may be
529     * used if brevity is a higher priority than readability. 
530     * 
531     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
532     * 
533     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
534     * useful in {@link RJArrIntoPrimArray}.
535     */
536    public static final int RETURN_DEFVAL_ON_STR = RN_S << 1;
537
538    /** Identical to flag-mask field <B>{@link #RETURN_DEFVAL_ON_STR}</B> */
539    public static final int RD_S = RETURN_DEFVAL_ON_STR;
540
541    /**
542     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
543     * {@link JsonArray} index-locations that contain a {@link JsonString}.
544     * 
545     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
546     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
547     * by the number of skipped-indices</I>.
548     * 
549     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
550     * 
551     * <BR />The flag-mask <B>{@link #S_S}</B> is an abbreviated but identical value that may be
552     * used if brevity is a higher priority than readability. 
553     * 
554     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
555     * 
556     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
557     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
558     * be applied to array-processing methods.
559     */
560    public static final int SKIP_ON_STR = RD_S << 1;
561
562    /** Identical to flag-mask field <B>{@link #SKIP_ON_STR}</B> */
563    public static final int S_S = SKIP_ON_STR;
564
565    /**
566     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
567     * {@link JsonArray} index-locations that contain a <B STYLE='color: red'>Zero-Length</B>
568     * {@link JsonString}.
569     * 
570     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
571     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
572     * by the number of skipped-indices</I>.
573     * 
574     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
575     * 
576     * <BR />The flag-mask <B>{@link #S_ZLS}</B> is an abbreviated but identical value that may be
577     * used if brevity is a higher priority than readability. 
578     * 
579     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
580     * 
581     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
582     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
583     * be applied to array-processing methods.
584     */
585    public static final int SKIP_ON_0LEN_STR = S_S << 1;
586
587    /** Identical to flag-mask field <B>{@link #SKIP_ON_0LEN_STR}</B> */
588    public static final int S_ZLS = SKIP_ON_0LEN_STR;
589
590    /**
591     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
592     * {@link JsonArray} index-locations that contain a {@link JsonString} that, when parsed,
593     * generate any parse-exceptions, such as {@code NumberFormatException}.
594     * 
595     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
596     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
597     * by the number of skipped-indices</I>.
598     * 
599     * <BR /><BR /><B STYLE='color: red;'>SPEX: String Parse Exception</B>
600     * 
601     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
602     * 
603     * <BR />The flag-mask <B>{@link #S_SPEX}</B> is an abbreviated but identical value that may be
604     * used if brevity is a higher priority than readability. 
605     * 
606     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
607     * 
608     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
609     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
610     * be applied to array-processing methods.
611     */
612    public static final int SKIP_ON_SPEX = S_ZLS << 1;
613
614    /** Identical to flag-mask field <B>{@link #SKIP_ON_SPEX}</B> */
615    public static final int S_SPEX = SKIP_ON_SPEX;
616
617    /**
618     * Instructs an array / stream builder method to <B STYLE='color: red;'>skip</B> any
619     * {@link JsonArray} index-locations that contain an inapplicable
620     * <B STYLE='color: red;'>Json-Type</B> - such as {@code JsonValue.TRUE},
621     * {@code JsonValue.FALSE}, {@code JsonObject}, a nested {@code JsonArray} etc...
622     * 
623     * <BR /><BR />When an array-index location is skipped during a converstion, the returned 
624     * stream will simply have a size shorter than the input {@code JsonArray's} size<I>, shortened
625     * by the number of skipped-indices</I>.
626     * 
627     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
628     * 
629     * <BR />The flag-mask <B>{@link #S_WT}</B> is an abbreviated but identical value that may be
630     * used if brevity is a higher priority than readability. 
631     * 
632     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Arrays Only:</B>
633     * 
634     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
635     * useful in {@link RJArrIntoPrimArray}.  Any flag which begins with {@code 'SKIP'} will only
636     * be applied to array-processing methods.
637     */
638    public static final int SKIP_ON_WRONG_JSONTYPE = S_SPEX << 1;
639
640    /** Identical to flag-mask field <B>{@link #SKIP_ON_WRONG_JSONTYPE}</B> */
641    public static final int S_WT = SKIP_ON_WRONG_JSONTYPE;
642
643
644    // ********************************************************************************************
645    // ********************************************************************************************
646    // ADDITIONAL: RJArrIntoPrimArray-Specific Flags
647    // ********************************************************************************************
648    // ********************************************************************************************
649
650
651    /**
652     * Instructs the {@code Stream<String>} (array/stream) builder method to invoke 
653     * {@link JsonValue#toString} whenever a type other than {@link JsonString} is found in an
654     * array position.  This flag is only applicable when converting a {@link JsonArray} into a
655     * {@code String[]}-Array.
656     * 
657     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
658     * 
659     * <BR />The flag-mask <B>{@link #RTS_WT}</B> is an abbreviated but identical value that may be
660     * used if brevity is a higher priority than readability. 
661     * 
662     * <BR /><BR /><B CLASS=JDDescLabel>For Specific Method Only:</B>
663     * 
664     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON}, and is only
665     * useful in invocations of method {@link RJArrIntoStream#strArr}.
666     */
667    public static final int RETURN_TOSTRING_ON_WRONGTYPE = S_WT << 1;
668
669    /** Identical to flag-mask field <B>{@link #RETURN_TOSTRING_ON_WRONGTYPE}</B> */
670    public static final int RTS_WT = RETURN_TOSTRING_ON_WRONGTYPE;
671
672
673    // ********************************************************************************************
674    // ********************************************************************************************
675    // ADDITIONAL: RJArrDimN Specific Flags
676    // ********************************************************************************************
677    // ********************************************************************************************
678
679
680    /**
681     * Instructs the multi-dimensional array-builder method to place a null in an array when
682     * it encounters a {@link JsonArray} element that is not a sub-array, but rather some other
683     * non-null <B STYLE='color: red;'>Json-Type</B>  This flag is only applicable when converting
684     * a {@link JsonArray} using one of the multi-dimensional array-processors in class
685     * {@link RJArrDimN}.
686     * 
687     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
688     * 
689     * <BR />The flag-mask <B>{@link #IN_NSAT}</B> is an abbreviated but identical value that may
690     * be used if brevity is a higher priority than readability. 
691     * 
692     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B>
693     * 
694     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in
695     * {@link RJArrIntoPrimArray}.  It is only used in processing multi-dimensional arrays (by
696     * class {@link RJArrDimN}).
697     */
698    public static final int INSERT_NULL_ON_NON_SUBARRAY_TYPE = RTS_WT << 1;
699
700    /** Identical to flag-mask field <B>{@link #INSERT_NULL_ON_NON_SUBARRAY_TYPE}</B> */
701    public static final int IN_NSAT = INSERT_NULL_ON_NON_SUBARRAY_TYPE;
702
703    /**
704     * Instructs the multi-dimensional array-builder method to skip the element when it encounters
705     * a {@link JsonArray} element that is not a sub-array, but rather some other non-null
706     * <B STYLE='color: red;'>Json-Type</B>  This flag is only applicable when converting
707     * a {@link JsonArray} using one of the multi-dimensional array-processors in class
708     * {@link RJArrDimN}.
709     * 
710     * <BR /><BR /><B CLASS=JDDescLabel>Abbreviation:</B>
711     * 
712     * <BR />The flag-mask <B>{@link #S_NSAT}</B> is an abbreviated but identical value that may be
713     * used if brevity is a higher priority than readability. 
714     * 
715     * <BR /><BR /><B CLASS=JDDescLabel>For Reading Multi-Dimensional Arrays Only:</B>
716     * 
717     * <BR />This flag is ignored, completely, by all methods in {@link ReadJSON} and in
718     * {@link RJArrIntoPrimArray}.  It is only used in processing multi-dimensional arrays (by
719     * class {@link RJArrDimN}).
720     */
721    public static final int SKIP_ON_NON_SUBARRAY_TYPE = IN_NSAT << 1;
722
723    /** Identical to flag-mask field <B>{@link #SKIP_ON_NON_SUBARRAY_TYPE}</B> */
724    public static final int S_NSAT = SKIP_ON_NON_SUBARRAY_TYPE;
725
726    /** 
727     * These are eliminated / removed from any call to a method which returns either an array
728     * of Java Primitives or a Java Primitive Stream.  These are also filtered from a call to class
729     * that invokes a Java Primitive-Consumer
730     * 
731     * @see RJArrIntoPrimStream#intArr(JsonArray, int, int, ToIntFunction)
732     * @see RJArrIntoPrimStream#longArr(JsonArray, long, int, ToLongFunction)
733     * @see RJArrIntoPrimStream#doubleArr(JsonArray, double, int, ToDoubleFunction)
734     * 
735     * @see RJArrIntoPrimConsumer
736     */
737    public static final int NOT_ALLOWED_RET_NULL_MASKS = ~(RETURN_NULL_ON_ANY_ALL |
738        RETURN_NULL_ON_AEX | RETURN_NULL_ON_NULL | RETURN_NULL_ON_SPEX | RETURN_NULL_ON_STR |
739        RETURN_NULL_ON_0LEN_STR | RETURN_NULL_ON_WRONG_JSONTYPE | INSERT_NULL_ON_NON_SUBARRAY_TYPE);
740}