uk.ac.starlink.votable

## Class StringElementSizer

- java.lang.Object
- - uk.ac.starlink.votable.StringElementSizer

-     public abstract class StringElementSizer
      extends java.lang.Object

  Object which is able to provide element sizes (string lengths) for table columns containing String[] arrays.

  This functionality is required when writing VOTable output; the FIELD headers need to have the common length of the strings, since VOTable output may contain variable-length arrays of fixed-length strings, but not fixed-length arrays of variable-length strings.

  A number of implementations are provided. The basic approaches are to read all the elements and find the maximum string length, which in general requires an extra pass through the data, or just provide some sort of guess.

  Since:
    19 Jun 2025

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static StringElementSizer` | `ASSERT_UNUSED` If called upon to provide length values, a false assertion is made.
    `static StringElementSizer` | `ERROR_IF_USED` If called upon to provide length values, an error will be raised.
    `static StringElementSizer` | `FIXED2` A fixed element length of 2 is used.
    `static StringElementSizer` | `NOCALC` The existing string length values, which may not be legal, are copied.
    `static StringElementSizer` | `READ` All elements are read and the maximum length used.
    `static StringElementSizer` | `SAMPLE` The first few elements are read and the maximum length used.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `StringElementSizer()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract int[]` | `calculateStringArrayElementSizes(StarTable table, int[] icols)` Fills in element length values for string array-valued columns in a supplied table.
    `static StringElementSizer` | `createFixedSizer(int elSize)` Creates an instance that reports a fixed length for all strings.
    `static StringElementSizer` | `createSampleReadSizer(int maxRow)` Creates an instance which reads some or all of the data to determine the maximum string length.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### NOCALC

          public static final StringElementSizer NOCALC

      The existing string length values, which may not be legal, are copied.

    - #### READ

          public static final StringElementSizer READ

      All elements are read and the maximum length used.

    - #### SAMPLE

          public static final StringElementSizer SAMPLE

      The first few elements are read and the maximum length used.

    - #### FIXED2

          public static final StringElementSizer FIXED2

      A fixed element length of 2 is used.

    - #### ERROR_IF_USED

          public static final StringElementSizer ERROR_IF_USED

      If called upon to provide length values, an error will be raised.

    - #### ASSERT_UNUSED

          public static final StringElementSizer ASSERT_UNUSED

      If called upon to provide length values, a false assertion is made.

  - ### Constructor Detail

    - #### StringElementSizer

          public StringElementSizer()

  - ### Method Detail

    - #### calculateStringArrayElementSizes

          public abstract int[] calculateStringArrayElementSizes(StarTable table,
                                                                 int[] icols)
                                                          throws java.io.IOException

      Fills in element length values for string array-valued columns in a supplied table.

      The return value is an array the same size as the input `icols` array whose elements are the calculated string lengths (`ValueInfo.getElementSize()`) for the corresponding column indices.

      Parameters:
        `table` - input table
        `icols` - index array of String[]-valued columns whose element lengths need to be determined
      Throws:
        `java.io.IOException`

    - #### createFixedSizer

          public static StringElementSizer createFixedSizer(int elSize)

      Creates an instance that reports a fixed length for all strings.
      Parameters:
        `elSize` - fixed string length
      Returns:
        new sizer

    - #### createSampleReadSizer

          public static StringElementSizer createSampleReadSizer(int maxRow)

      Creates an instance which reads some or all of the data to determine the maximum string length.
      Parameters:
        `maxRow` - maximum number of rows to read; if not positive, all rows are read
      Returns:
        new instance