001package Torello.JSON;
002
003import Torello.Java.StringParse;
004import Torello.Java.UnreachableError;
005
006import Torello.Java.Additional.Ret3;
007import Torello.Java.Additional.EffectivelyFinal;
008import Torello.Java.Additional.Counter;
009
010import Torello.Java.Function.ToByteFunction;
011import Torello.Java.Function.ToFloatFunction;
012import Torello.Java.Function.ToShortFunction;
013
014import Torello.JavaDoc.Annotations.StaticFunctional;
015import Torello.JavaDoc.Annotations.JDHeaderBackgroundImg;
016import Torello.JavaDoc.Annotations.LinkJavaSource;
017
018import Torello.JavaDoc.Annotations.IntoHTMLTable;
019import static Torello.JavaDoc.Annotations.IntoHTMLTable.Background.GreenDither;
020import static Torello.JavaDoc.Annotations.IntoHTMLTable.Background.BlueDither;
021
022import java.util.Objects;
023
024import java.util.stream.Stream;
025import java.util.stream.IntStream;
026import java.util.stream.LongStream;
027import java.util.stream.DoubleStream;
028
029import java.util.function.ToIntFunction;
030import java.util.function.ToLongFunction;
031import java.util.function.ToDoubleFunction;
032import java.util.function.Predicate;
033import java.util.function.Function;
034
035import javax.json.JsonArray;
036import javax.json.Json;
037
038import static Torello.JSON.JFlag.NOT_ALLOWED_RET_NULL_MASKS;
039
040
041/**
042 * Parses Multi-Dimensional JSON Array's into Multi-Dimensional Java Array's.
043 * 
044 * <EMBED CLASS='external-html' DATA-FILE-ID=ALL_CLASSES_NOTE>
045 * <EMBED CLASS='external-html' DATA-FILE-ID=RJA_DIM_N>
046 * 
047 * <BR /><HR> <BR />
048 * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN>
049 * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_PT_DIMN>
050 *
051 * <EMBED CLASS=globalDefs DATA-A_AN=A>
052 * @see Json
053 * @see JsonArray
054 */
055@StaticFunctional
056@JDHeaderBackgroundImg(EmbedTagFileID="RJA_JDHBI_DIM_N")
057public class RJArrDimN
058{
059    private RJArrDimN() { }
060
061
062    // ********************************************************************************************
063    // ********************************************************************************************
064    // Primitive Multi-Dimensional Array Methods
065    // ********************************************************************************************
066    // ********************************************************************************************
067
068
069    /**
070     * <EMBED CLASS=defs DATA-A_AN=An DATA-TYPE=int DATA-DEFVAL="-1">
071     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
072     */
073    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Primitive-Integers")
074    @LinkJavaSource(handle="BASIC_TYPES", name="INTEGER")
075    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
076    public static <T> T intArr(
077            final JsonArray             ja,
078            final int                   defaultValue,
079            final int                   FLAGS,
080            final ToIntFunction<String> optionalUserParser,
081            final Class<T>              retArrClass
082        )
083    {
084        return ProcessMultiDimJsonArray.jsonArrayToJava(
085            ja,
086            new SETTINGS_REC_BUILDER<Integer, IntStream>(
087                defaultValue,
088                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,
089                (optionalUserParser == null) ? null : optionalUserParser::applyAsInt,
090                BASIC_TYPES.PRIMITIVE_INTEGER()
091            )
092            .dimNArrayIntPrim(),
093            retArrClass
094        );
095    }
096
097    /**
098     * <EMBED CLASS=defs DATA-TYPE=long DATA-DEFVAL="-1">
099     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
100     */
101    @IntoHTMLTable(background=BlueDither,
102        title="Multi-Dimensional Array of Primitive Long-Integers")
103    @LinkJavaSource(handle="BASIC_TYPES", name="LONG")
104    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
105    public static <T> T longArr(
106            final JsonArray                 ja,
107            final long                      defaultValue,
108            final int                       FLAGS,
109            final ToLongFunction<String>    optionalUserParser,
110            final Class<T>                  retArrClass
111        )
112    {
113        return ProcessMultiDimJsonArray.jsonArrayToJava(
114            ja,
115            new SETTINGS_REC_BUILDER<Long, LongStream>(
116                defaultValue,
117                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,
118                (optionalUserParser == null) ? null : optionalUserParser::applyAsLong,
119                BASIC_TYPES.PRIMITIVE_LONG()
120            )
121            .dimNArrayLongPrim(),
122            retArrClass
123        );
124    }
125
126    /**
127     * <EMBED CLASS=defs DATA-TYPE=double DATA-DEFVAL="-1.0">
128     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
129     */
130    @IntoHTMLTable(background=GreenDither,
131        title="Multi-Dimensional Array of Primitive-Doubles")
132    @LinkJavaSource(handle="BASIC_TYPES", name="DOUBLE")
133    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
134    public static <T> T doubleArr(
135            final JsonArray                 ja,
136            final double                    defaultValue,
137            final int                       FLAGS,
138            final ToDoubleFunction<String>  optionalUserParser,
139            final Class<T>                  retArrClass
140        )
141    {
142        return ProcessMultiDimJsonArray.jsonArrayToJava(
143            ja,
144            new SETTINGS_REC_BUILDER<Double, DoubleStream>(
145                defaultValue,
146                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
147                (optionalUserParser == null) ? null : optionalUserParser::applyAsDouble,
148                BASIC_TYPES.PRIMITIVE_DOUBLE()
149            )
150            .dimNArrayDoublePrim(),
151            retArrClass
152        );
153    }
154
155    /**
156     * <EMBED CLASS=defs DATA-TYPE=short DATA-DEFVAL="-1">
157     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
158     */
159    @IntoHTMLTable(background=BlueDither,
160        title="Multi-Dimensional Array of Primitive Short-Integers")
161    @LinkJavaSource(handle="BASIC_TYPES", name="SHORT")
162    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
163    public static <T> T shortArr(
164            final JsonArray                 ja,
165            final short                     defaultValue,
166            final int                       FLAGS,
167            final ToShortFunction<String>   optionalUserParser,
168            final Class<T>                  retArrClass
169        )
170    {
171        return ProcessMultiDimJsonArray.jsonArrayToJava(
172            ja,
173            new SETTINGS_REC_BUILDER<Short, Stream<Short>>(
174                defaultValue,
175                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
176                (optionalUserParser == null) ? null : optionalUserParser::applyAsShort,
177                BASIC_TYPES.PRIMITIVE_SHORT()
178            )
179            .dimNArray(),
180            retArrClass
181        );
182    }
183
184    /**
185     * <EMBED CLASS=defs DATA-TYPE=byte DATA-DEFVAL="-1">
186     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
187     */
188    @IntoHTMLTable(background=GreenDither,
189        title="Multi-Dimensional Array of Primitive-Bytes")
190    @LinkJavaSource(handle="BASIC_TYPES", name="BYTE")
191    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
192    public static <T> T byteArr(
193            final JsonArray                 ja,
194            final byte                      defaultValue,
195            final int                       FLAGS,
196            final ToByteFunction<String>    optionalUserParser,
197            final Class<T>                  retArrClass
198        )
199    {
200        return ProcessMultiDimJsonArray.jsonArrayToJava(
201            ja,
202            new SETTINGS_REC_BUILDER<Byte, Stream<Byte>>(
203                defaultValue,
204                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
205                (optionalUserParser == null) ? null : optionalUserParser::applyAsByte,
206                BASIC_TYPES.PRIMITIVE_BYTE()
207            )
208            .dimNArray(),
209            retArrClass
210        );
211    }
212
213    /**
214     * <EMBED CLASS=defs DATA-TYPE=float DATA-DEFVAL="-1.0f">
215     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
216     */
217    @IntoHTMLTable(background=BlueDither,
218        title="Multi-Dimensional Array of Primitive-Floats")
219    @LinkJavaSource(handle="BASIC_TYPES", name="FLOAT")
220    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
221    public static <T> T floatArr(
222            final JsonArray                 ja,
223            final float                     defaultValue,
224            final int                       FLAGS,
225            final ToFloatFunction<String>   optionalUserParser,
226            final Class<T>                  retArrClass
227        )
228    {
229        return ProcessMultiDimJsonArray.jsonArrayToJava(
230            ja,
231            new SETTINGS_REC_BUILDER<Float, Stream<Float>>(
232                defaultValue,
233                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
234                (optionalUserParser == null) ? null : optionalUserParser::applyAsFloat,
235                BASIC_TYPES.PRIMITIVE_FLOAT()
236            )
237            .dimNArray(),
238            retArrClass
239        );
240    }
241
242    /**
243     * <EMBED CLASS=defs DATA-TYPE=boolean DATA-DEFVAL="false">
244     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_PRIM>
245     */
246    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Primitive-Booleans")
247    @LinkJavaSource(handle="BASIC_TYPES", name="BOOLEAN")
248    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
249    public static <T> T booleanArr(
250            final JsonArray         ja,
251            final boolean           defaultValue,
252            final int               FLAGS,
253            final Predicate<String> optionalUserParser,
254            final Class<T>          retArrClass
255        )
256    {
257        return ProcessMultiDimJsonArray.jsonArrayToJava(
258            ja,
259            new SETTINGS_REC_BUILDER<Boolean, Stream<Boolean>>(
260                defaultValue,
261                FLAGS & NOT_ALLOWED_RET_NULL_MASKS,    
262                (optionalUserParser == null) ? null : optionalUserParser::test,
263                BASIC_TYPES.PRIMITIVE_BOOLEAN()
264            )
265            .dimNArray(),
266            retArrClass
267        );
268    }
269
270
271    // ********************************************************************************************
272    // ********************************************************************************************
273    // Boxed-Primitive Multi-Dimensional Array Methods
274    // ********************************************************************************************
275    // ********************************************************************************************
276
277
278    /**
279     * <EMBED CLASS=defs DATA-A_AN=An DATA-TYPE=Integer DATA-METH_NAME=INTEGER DATA-DEF_VAL="-1">
280     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
281     */
282    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Integers")
283    @LinkJavaSource(handle="BASIC_TYPES", name="INTEGER")
284    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
285    public static <T> T arrINTEGER(
286            final JsonArray                 ja,
287            final int                       defaultValue,
288            final int                       FLAGS,
289            final Function<String, Integer> optionalUserParser,
290            final Class<T>                  retArrClass
291        )
292    {
293        return ProcessMultiDimJsonArray.jsonArrayToJava(
294            ja,
295            new SETTINGS_REC_BUILDER<Integer, Stream<Integer>>(
296                defaultValue,
297                FLAGS,
298                optionalUserParser,
299                BASIC_TYPES.BOXED_INTEGER()
300            )
301            .dimNArray(),
302            retArrClass
303        );
304    }
305
306    /**
307     * <EMBED CLASS=defs DATA-TYPE=Long DATA-METH_NAME=LONG DATA-DEF_VAL="-1">
308     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
309     */
310    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed Long-Integers")
311    @LinkJavaSource(handle="BASIC_TYPES", name="LONG")
312    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
313    public static <T> T arrLONG(
314            final JsonArray                 ja,
315            final long                      defaultValue,
316            final int                       FLAGS,
317            final Function<String, Long>    optionalUserParser,
318            final Class<T>                  retArrClass
319        )
320    {
321        return ProcessMultiDimJsonArray.jsonArrayToJava(
322            ja,
323            new SETTINGS_REC_BUILDER<Long, Stream<Long>>(
324                defaultValue,
325                FLAGS,
326                optionalUserParser,
327                BASIC_TYPES.BOXED_LONG()
328            )
329            .dimNArray(),
330            retArrClass
331        );
332    }
333
334    /**
335     * <EMBED CLASS=defs DATA-TYPE=Double DATA-METH_NAME=DOUBLE DATA-DEF_VAL="-1.0">
336     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
337     */
338    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Doubles")
339    @LinkJavaSource(handle="BASIC_TYPES", name="DOUBLE")
340    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
341    public static <T> T arrDOUBLE(
342            final JsonArray                 ja,
343            final double                    defaultValue,
344            final int                       FLAGS,
345            final Function<String, Double>  optionalUserParser,
346            final Class<T>                  retArrClass
347        )
348    {
349        return ProcessMultiDimJsonArray.jsonArrayToJava(
350            ja,
351            new SETTINGS_REC_BUILDER<Double, Stream<Double>>(
352                defaultValue,
353                FLAGS,
354                optionalUserParser,
355                BASIC_TYPES.BOXED_DOUBLE()
356            )
357            .dimNArray(),
358            retArrClass
359        );
360    }
361
362    /**
363     * <EMBED CLASS=defs DATA-TYPE=Short DATA-METH_NAME=SHORT DATA-DEF_VAL="-1">
364     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
365     */
366    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed Short-Integers")
367    @LinkJavaSource(handle="BASIC_TYPES", name="SHORT")
368    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
369    public static <T> T arrSHORT(
370            final JsonArray                 ja,
371            final short                     defaultValue,
372            final int                       FLAGS,
373            final Function<String, Short>   optionalUserParser,
374            final Class<T>                  retArrClass
375        )
376    {
377        return ProcessMultiDimJsonArray.jsonArrayToJava(
378            ja,
379            new SETTINGS_REC_BUILDER<Short, Stream<Short>>(
380                defaultValue,
381                FLAGS,
382                optionalUserParser,
383                BASIC_TYPES.BOXED_SHORT()
384            )
385            .dimNArray(),
386            retArrClass
387        );
388    }
389
390    /**
391     * <EMBED CLASS=defs DATA-TYPE=Byte DATA-METH_NAME=BYTE DATA-DEF_VAL="-1">
392     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
393     */
394    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Bytes")
395    @LinkJavaSource(handle="BASIC_TYPES", name="BYTE")
396    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
397    public static <T> T arrBYTE(
398            final JsonArray                 ja,
399            final byte                      defaultValue,
400            final int                       FLAGS,
401            final Function<String, Byte>    optionalUserParser,
402            final Class<T>                  retArrClass
403        )
404    {
405        return ProcessMultiDimJsonArray.jsonArrayToJava(
406            ja,
407            new SETTINGS_REC_BUILDER<Byte, Stream<Byte>>(
408                defaultValue,
409                FLAGS,
410                optionalUserParser,
411                BASIC_TYPES.BOXED_BYTE()
412            )
413            .dimNArray(),
414            retArrClass
415        );
416    }
417
418    /**
419     * <EMBED CLASS=defs DATA-TYPE=Float DATA-METH_NAME=FLOAT DATA-DEF_VAL="-1.0f">
420     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
421     */
422    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Boxed-Floats")
423    @LinkJavaSource(handle="BASIC_TYPES", name="FLOAT")
424    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
425    public static <T> T arrFLOAT(
426            final JsonArray                 ja,
427            final float                     defaultValue,
428            final int                       FLAGS,
429            final Function<String, Float>   optionalUserParser,
430            final Class<T>                  retArrClass
431        )
432    {
433        return ProcessMultiDimJsonArray.jsonArrayToJava(
434            ja,
435            new SETTINGS_REC_BUILDER<Float, Stream<Float>>(
436                defaultValue,
437                FLAGS,
438                optionalUserParser,
439                BASIC_TYPES.BOXED_FLOAT()
440            )
441            .dimNArray(),
442            retArrClass
443        );
444    }
445
446    /**
447     * <EMBED CLASS=defs DATA-TYPE=Boolean DATA-METH_NAME=BOOLEAN DATA-DEF_VAL=false>
448     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
449     */
450    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Boxed-Booleans")
451    @LinkJavaSource(handle="BASIC_TYPES", name="BOOLEAN")
452    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
453    public static <T> T arrBOOLEAN(
454            final JsonArray                 ja,
455            final boolean                   defaultValue,
456            final int                       FLAGS,
457            final Function<String, Boolean> optionalUserParser,
458            final Class<T>                  retArrClass
459        )
460    {
461        return ProcessMultiDimJsonArray.jsonArrayToJava(
462            ja,
463            new SETTINGS_REC_BUILDER<Boolean, Stream<Boolean>>(
464                defaultValue,
465                FLAGS,
466                optionalUserParser,
467                BASIC_TYPES.BOXED_BOOLEAN()
468            )
469            .dimNArray(),
470            retArrClass
471        );
472    }
473
474    /**
475     * <EMBED CLASS=defs DATA-TYPE=Number DATA-METH_NAME=Number DATA-DEF_VAL=0>
476     * <EMBED CLASS='external-html' DATA-FILE-ID=RJ_ARR_DIMN_METH_BOXED>
477     */
478    @IntoHTMLTable(background=GreenDither, title="Multi-Dimensional Array of Best-Fit Boxed-Numbers")
479    @LinkJavaSource(handle="BASIC_TYPES", name="NUMBER")
480    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
481    public static <T> T arrNumber(
482            final JsonArray                 ja,
483            final Number                    defaultValue,
484            final int                       FLAGS,
485            final Function<String, Number>  optionalUserParser,
486            final Class<T>                  retArrClass
487        )
488    {
489        return ProcessMultiDimJsonArray.jsonArrayToJava(
490            ja,
491            new SETTINGS_REC_BUILDER<Number, Stream<Number>>(
492                defaultValue,
493                FLAGS,
494                optionalUserParser,
495                BASIC_TYPES.NUMBER_REC()
496            )
497            .dimNArray(),
498            retArrClass
499        );
500    }
501
502
503    // *******************************************************************************************
504    // *******************************************************************************************
505    // Non-Primitive Multi-Dimensional Array Methods
506    // *******************************************************************************************
507    // *******************************************************************************************
508
509
510    /**
511     * <BR>Invokes: {@link ProcessMultiDimJsonArray#jsonArrayToJava(JsonArray, SettingsRec, Class)}
512     * <BR>Passes: {@code String} Configurations / SettingsRec
513     * <BR>See: Class {@link JFlag} for more information about parameter {@code 'FLAGS'}.
514     * <BR>Note: {@code retArrClass} must be a multi-dimensinal {@code String}-array.
515     * <BR>:(See last <B>"return-type"</B> parameter in example below)
516     * 
517     * <BR>COL-SPAN-2:
518     * <DIV CLASS=LOC>{@code
519     * String[][] arr = ReadArrJSON.DimN.strArr(jsonArray, null, 0, String[][].class);
520     * }</DIV>
521     */
522    @IntoHTMLTable(background=BlueDither, title="Multi-Dimensional Array of Strings")
523    @LinkJavaSource(handle="BASIC_TYPES", name="STRING")
524    @LinkJavaSource(handle="SETTINGS_REC_BUILDER", name="dimNArray")
525    public static <T> T strArr(
526            final JsonArray ja,
527            final String    defaultValue,
528            final int       FLAGS,
529            final Class<T>  retArrClass
530        )
531    {
532        return ProcessMultiDimJsonArray.jsonArrayToJava(
533            ja, 
534            new SETTINGS_REC_BUILDER<String, Stream<String>>(
535                defaultValue,
536                FLAGS,
537                null, // no optional user parser, input is supposed to be a string
538                BASIC_TYPES.STRING_REC()
539            )
540            .dimNArray(),
541            retArrClass
542        );
543    }
544}
545