====== Programmatically Creating Complex SecsFormat00 Objects from Java Arrays ======


===== 🧩 Convert Mixed-Type Nested Arrays: sf00FromNested(Object data) =====

Recursively converts a nested ''Object'' array into a hierarchical SECS structure, inferring SECS types based on the Java type of each leaf element.

You may use this method when your structure may contain integers, floats, doubles, longs, or strings. Each array level becomes a ''SecsFormat00''.

==== Example method ====

<code java>
/**
 * Recursively converts a nested {@code Object} (array or leaf) into a hierarchical SECS structure.
 * 
 * Arrays (including multidimensional ones) become nested {@link SecsFormat00}, and leaf elements are converted
 * to SECS types based on their Java type.
 *
 * @param data the nested Object to convert (can be an Object[], Object[][], etc.)
 * @return a {@link SecsFormat00} representation of the structure
 */
public static SecsFormat00 sf00FromNested(Object data) {
    SecsFormat00 list = new SecsFormat00();

    if (data instanceof Object[]) {
        for (Object element : (Object[]) data) {
            if (element instanceof Object[]) {
                list.add(sf00FromNested(element));
            } else if (element instanceof Integer) {
                list.add(new SecsFormat34((Integer) element));
            } else if (element instanceof Long) {
                list.add(new SecsFormat30((Long) element));
            } else if (element instanceof Float) {
                list.add(new SecsFormat44((Float) element));
            } else if (element instanceof Double) {
                list.add(new SecsFormat40((Double) element));
            } else {
                list.add(new SecsFormat20(String.valueOf(element)));
            }
        }
    } else {
        throw new IllegalArgumentException("Input must be an Object array at the top level");
    }

    return list;
}
</code>

==== Example usage ====

<code java>
Object[][] example = {
    {"abc", 123, 1.23},
    {"xyz", new Object[] { 456L, 7.89f }},
};

SecsFormat00 result = sf00FromNested(example);
</code>

**Expected output:**

<code>
[[<A 'abc'>, <I4 123>, <F8 1.23000>], [<A 'xyz'>, [<I8 456>, <F4 7.89000>]]]
</code>


===== 🔤 Convert All-String Nested Arrays: sf00FromNestedStrings(Object data) =====

Recursively converts a nested ''Object'' array into a SECS structure assuming all leaf elements are strings or nulls. This is often better when you know the expected SecsFormat of your values because the type can be defined explicitly.

==== Example method ====

<code java>
/**
 * Recursively converts a nested {@code Object} (array or leaf) into a SECS structure assuming all leaves are Strings.
 * 
 * Use this when all data is guaranteed to be Strings (or nulls), to avoid type checks.
 *
 * @param data a nested Object (e.g., {@code String[][]}, {@code String[][][]}, etc.)
 * @return a {@link SecsFormat00} structure with all leaves as {@link SecsFormat20}
 */
public static SecsFormat00 sf00FromNestedStrings(Object data) {
    SecsFormat00 list = new SecsFormat00();

    if (data instanceof Object[]) {
        for (Object element : (Object[]) data) {
            if (element instanceof Object[]) {
                list.add(sf00FromNestedStrings(element));
            } else {
                list.add(new SecsFormat20(String.valueOf(element)));
            }
        }
    } else {
        throw new IllegalArgumentException("Input must be an Object array at the top level");
    }

    return list;
}
</code>

==== Example usage ====

<code java>
String[][][] nestedStrings = {
    {
        {"A", "B"},
        {"C", "D"}
    },
    {
        {"E", "F"},
        {"G", "H"}
    }
};

SecsFormat00 result = sf00FromNestedStrings(nestedStrings);
</code>

**Expected output:**

<code>
[[[<A 'A'>, <A 'B'>], [<A 'C'>, <A 'D'>]], [[<A 'E'>, <A 'F'>], [<A 'G'>, <A 'H'>]]]
</code>


===== 📦 Convert Structured Triple Arrays: sf00FromNestedStructuredTriple(Object data) =====

Recursively converts a nested ''Object'' array into a hierarchical SECS structure, using explicit types at the leaf. In this example,  
Non-array elements are assumed to be leaf-level triples: **[String, Float, Integer]**.  
Arrays are recursively processed into nested ''SecsFormat00'' structures.

==== Example method ====

<code java>
/**
 * Recursively converts a nested {@code Object} array into a hierarchical SECS structure.
 * <p>
 * Non-array elements are assumed to be leaf-level triples: [String, Float, Integer].
 * Arrays are recursively processed into nested {@link SecsFormat00} structures.
 *
 * @param data the nested Object array
 * @return a {@link SecsFormat00} representing the structured SECS data
 * @throws IllegalArgumentException if the leaf triple is invalid or structure is malformed
 */
public static SecsFormat00 sf00FromNestedStructuredTriple(Object data) {
    if (!(data instanceof Object[])) {
        throw new IllegalArgumentException("Input must be an Object[]");
    }

    Object[] array = (Object[]) data;

    // Check if this is a valid leaf triple
    if (array.length == 3 &&
            array[0] instanceof String &&
            array[1] instanceof Float &&
            array[2] instanceof Integer) {

        SecsFormat00 triple = new SecsFormat00();
        triple.add(new SecsFormat20((String) array[0]));
        triple.add(new SecsFormat44((Float) array[1]));
        triple.add(new SecsFormat34((Integer) array[2]));
        return triple;
    }

    // Otherwise, treat as nested structure
    SecsFormat00 list = new SecsFormat00();
    for (Object element : array) {
        if (!(element instanceof Object[])) {
            throw new IllegalArgumentException("Encountered non-array element where nested structure was expected");
        }
        list.add(sf00FromNestedStructuredTriple(element));
    }

    return list;
}
</code>

==== Example usage ====

<code java>
Object[] nested = {
    new Object[] {
        new Object[] { "abc", 1.5f, 42 },
        new Object[] { "def", 2.5f, 99 }
    },
    new Object[] {
        new Object[] { "ghi", 3.0f, 7 }
    }
};

SecsFormat00 result = sf00FromNestedStructuredTriple(nested);
</code>

**Expected output:**

<code>
[[[<A 'abc'>, <F4 1.50000>, <I4 42>], [<A 'def'>, <F4 2.50000>, <I4 99>]], [[<A 'ghi'>, <F4 3.00000>, <I4 7>]]]
</code>