====== CSV-to-SECS Structure Conversion Methods ======

These utility methods convert CSV files into hierarchical SECS structures using ''SecsFormat00'' as the container for nested data and typed leaf values. Depending on the use case, different parsing strategies can be applied.

Note that this can be useful because it is easy to parse CSV files without external dependencies, but you might prefer to use a CSV parsing library if your csv is not well behaved (for example, if your values can sometimes contain commas).

----

===== 🔤 Parse All-String CSV: sf00FromCsvFile(File file) =====

Parses a CSV file into a ''SecsFormat00'' structure assuming every cell should be treated as a string.

==== 📋 Description ====

  * Each row in the CSV becomes a list inside the outer ''SecsFormat00''.
  * All cell values are trimmed and added as ''SecsFormat20'' (ASCII).
  * Empty cells are preserved and converted into empty strings.

==== 💡 Example Code ====

<code java>
public static SecsFormat00 sf00FromCsvFile(File file) {
    SecsFormat00 outerList = new SecsFormat00();
    try (BufferedReader reader = new BufferedReader(new FileReader(file))) {
        String line;
        while ((line = reader.readLine()) != null) {
            String[] parts = line.split(",", -1); // preserve trailing empty columns
            SecsFormat00 rowList = new SecsFormat00();
            for (String part : parts) {
                rowList.add(new SecsFormat20(part.trim()));
            }
            outerList.add(rowList);
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
    return outerList;
}
</code>

==== 🧪 Example Input (CSV) ====

<code>
hello,world,123
abc,,xyz
</code>

==== ✅ Output Structure ====

<code>
[[<A 'hello'>, <A 'world'>, <A '123'>], [<A 'abc'>, <A ''>, <A 'xyz'>]]
</code>

----

===== 🧠 Parse CSV with Auto-Typed Values: sf00FromCsvFileAutomaticTypes(File file) =====

Parses a CSV file into a typed SECS structure by inferring types per cell.

==== 📋 Description ====

  * Each CSV row is a sublist in the resulting ''SecsFormat00''.
  * Each cell is evaluated in this order:
    - Try ''SecsFormat34'' (integer)
    - Try ''SecsFormat44'' (float)
    - Fallback to ''SecsFormat20'' (string)
  * Empty strings are handled as ''SecsFormat20("")''.

==== 💡 Example Code ====

<code java>
public static SecsFormat00 sf00FromCsvFileAutomaticTypes(File file) {
    SecsFormat00 outerList = new SecsFormat00();
    try (BufferedReader reader = new BufferedReader(new FileReader(file))) {
        String line;
        while ((line = reader.readLine()) != null) {
            String[] parts = line.split(",", -1); // preserve trailing empty columns
            SecsFormat00 rowList = new SecsFormat00();
            for (String part : parts) {
                String trimmed = part.trim();
                if (trimmed.isEmpty()) {
                    rowList.add(new SecsFormat20(""));
                    continue;
                }
                try {
                    int intVal = Integer.parseInt(trimmed);
                    rowList.add(new SecsFormat34(intVal));
                } catch (NumberFormatException e1) {
                    try {
                        double doubleVal = Double.parseDouble(trimmed);
                        rowList.add(new SecsFormat44(doubleVal));
                    } catch (NumberFormatException e2) {
                        rowList.add(new SecsFormat20(trimmed));
                    }
                }
            }
            outerList.add(rowList);
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
    return outerList;
}
</code>

==== 🧪 Example Input (CSV) ====

<code>
123,hello,45.6
,789,world
</code>

==== ✅ Output Structure ====

<code>
[[<I4 123>, <A 'hello'>, <F4 45.60000>], [<A ''>, <I4 789>, <A 'world'>]]
</code>

----

===== 🧩 Parse Strict Typed Tuples from CSV: sf00FromCsvFileTypedExample(File file) =====

Parses each row of a CSV into a fixed 3-field structure: ''[String, Double, Integer]''.

==== 📋 Description ====

  * Expected format: ''String, Double, Integer''
  * Each valid row becomes a 3-item ''SecsFormat00''.
  * If a row does not match the expected structure (wrong number or type of columns), it is skipped with a warning.

==== 💡 Example Code ====

<code java>
public static SecsFormat00 sf00FromCsvFileTypedExample(File file) {
    SecsFormat00 outerList = new SecsFormat00();
    try (BufferedReader reader = new BufferedReader(new FileReader(file))) {
        String line;
        while ((line = reader.readLine()) != null) {
            String[] parts = line.split(",", -1);
            if (parts.length != 3) {
                System.err.println("Skipping row: expected 3 columns, got " + parts.length + " → " + line);
                continue;
            }

            try {
                String str = parts[0].trim();
                double dbl = Double.parseDouble(parts[1].trim());
                int i = Integer.parseInt(parts[2].trim());

                SecsFormat00 rowList = new SecsFormat00();
                rowList.add(new SecsFormat20(str));
                rowList.add(new SecsFormat44(dbl));
                rowList.add(new SecsFormat34(i));

                outerList.add(rowList);
            } catch (NumberFormatException e) {
                System.err.println("Skipping row due to type mismatch: " + line);
            }
        }
    } catch (IOException e) {
        e.printStackTrace();
    }
    return outerList;
}
</code>

==== 🧪 Example Input (CSV) ====

<code>
alpha,1.23,100
beta,4.56,200
</code>

==== ✅ Output Structure ====

<code>
[[<A 'alpha'>, <F4 1.23000>, <I4 100>], [<A 'beta'>, <F4 4.56000>, <I4 200>]]
</code>