Package nom.tam.fits

Class BinaryTable.ColumnDesc

java.lang.Object
nom.tam.fits.BinaryTable.ColumnDesc
All Implemented Interfaces:
Cloneable
Enclosing class:
BinaryTable
public static class BinaryTable.ColumnDesc extends Object implements Cloneable
Describes the data type and shape stored in a binary table column.

  • Constructor Details

    • ColumnDesc

      public ColumnDesc(Class<?> base, int... dim) throws FitsException
      Creates a new column descriptor for the specified boxed Java type, and fixed array shape. The type may be any primitive type, or else String.class, Boolean.class (for FITS logicals), ComplexValue.class or ComplexValue.Float.class (for complex values with 64-bit and 32-bit precision, respectively). Whereas Boolean type columns will be stored as FITS logicals (1 element per byte), boolean types will be stored as packed bits (with up to 8 bits per byte).
      Parameters:
      base - The Java type of base elements that this column is designated to contain. For example int.class if the column will contain integers or arrays of integers.
      dim - the fixed dimensions of the table entries. For strings the trailing dimension must specify the fixed length of strings.
      Throws:
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

  • Method Details

    • name

      public BinaryTable.ColumnDesc name(String value) throws IllegalArgumentException
      Sets a user-specified name for this column. The specified name will be used as the TTYPEn value for this column.
      Parameters:
      value - The new name for this column.
      Returns:
      itself, to support builder patterns.
      Throws:
      IllegalArgumentException - If the name contains characters outside of the ASCII range of 0x20 - 0x7F allowed by FITS.
      Since:
      1.20
      See Also:

    • name

      public String name()
      Returns the name of this column, as it was stored or would be stored by a TTYPEn value in the FITS header.
      Returns:
      the name of this column
      Since:
      1.20
      See Also:

    • getQuantizer

      public Quantizer getQuantizer()
      Returns the conversion between decimal and integer data representations for the column data.
      Returns:
      the quantizer that converts between floating-point and integer data representations, which may be null.
      Since:
      1.20
      See Also:

    • setQuantizer

      public void setQuantizer(Quantizer q)
      Sets the conversion between decimal and integer data representations for the column data. If the table is read from a FITS input, the column's quantizer is automatically set if the Table HDU's header defines any of the TSCALn, TZEROn, or TNULLn keywords for the column. Users can override that by specifying another quatizer to use for the column, or dicard qunatizing by calling this method with a nullargument.
      Parameters:
      q - the quantizer that converts between floating-point and integer data representations, or null to not use any quantization, and instead rely on the generic rounding for decimal-integer conversions for this column.
      Since:
      1.20
      See Also:

    • getStringLength

      public final int getStringLength()
      Returns the maximum length of string elements contained in this colum, or -1 if this is not a string based column, or if there is no limit set to string size (e.g. in a variable-length column)
      Returns:
      the maximum length of string values stored in this column, or -1 if it is not as string column, or if its a string column containing strings of unconstrained variable length.
      Since:
      1.18
      See Also:

    • getStringDelimiter

      public final byte getStringDelimiter()
      Returns the string delimiter that separates packed substrings in variable-length string arrays.
      Returns:
      the delimiter byte value (usually between 0x20 and 0x7e) or 0 if no delimiter was set.
      See Also:

    • createForScalars

      public static BinaryTable.ColumnDesc createForScalars(Class<?> type) throws IllegalArgumentException, FitsException
      Creates a new column descriptor for a non-string based scalar column. The type may be any primitive type, or Boolean.class (for FITS logicals), ComplexValue.class or ComplexValue.Float.class (for complex values with 64-bit and 32-bit precision, respectively). Whereas Boolean type columns will be stored as FITS logicals (1 element per byte), boolean types will be stored as packed bits (with up to 8 bits per byte).
      Parameters:
      type - The Java type of base elements that this column is designated to contain. For example int.class if the column will contain integers or arrays of integers. It must not be String.class. To create scalar String columns use createForStrings(int) instead.
      Returns:
      the new column descriptor.
      Throws:
      IllegalArgumentException - if the type is String.class, for which you should be using createForStrings(int) instead.
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

    • createForFixedArrays

      public static BinaryTable.ColumnDesc createForFixedArrays(Class<?> type, int... dim) throws IllegalArgumentException, FitsException
      Creates a new column descriptor for fixed-shape non-string arrays. The type may be any primitive type, or else Boolean.class (for FITS logicals), ComplexValue.class or ComplexValue.Float.class (for complex values with 64-bit and 32-bit precision, respectively). Whereas Boolean type columns will be stored as FITS logicals (1 element per byte), boolean types will be stored as packed bits (with up to 8 bits per byte).
      Parameters:
      type - The Java type of base elements that this column is designated to contain. For example int.class if the column will contain integers or arrays of integers. It must not be String.class. To create scalar String columns use createForStrings(int) instead.
      dim - the fixed dimensions of the table entries. For strings the trailing dimension must specify the fixed length of strings.
      Returns:
      the new column descriptor.
      Throws:
      IllegalArgumentException - if the type is String.class, for which you should be using createForStrings(int, int[]) instead.
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

    • createForStrings

      public static BinaryTable.ColumnDesc createForStrings(int len) throws FitsException
      Creates a new column descriptor for single string entries of fixed maximum length.
      Parameters:
      len - The fixed string length in bytes.
      Returns:
      the new column descriptor
      Throws:
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

    • createForStrings

      public static BinaryTable.ColumnDesc createForStrings(int len, int... outerDims) throws FitsException
      Creates a new column descriptor for arrays of string entries of fixed maximum length.
      Parameters:
      len - The fixed string length in bytes.
      outerDims - The shape of string arrays
      Returns:
      the new column descriptor
      Throws:
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

    • createForVariableStringArrays

      public static BinaryTable.ColumnDesc createForVariableStringArrays(int len) throws FitsException
      Creates a new column descriptor for variable-length arrays of fixed-length string entries. Each string component will occupy exactly len bytes.
      Parameters:
      len - The fixed string storage length in bytes.
      Returns:
      the new column descriptor
      Throws:
      FitsException - if the column could not be created.
      Since:
      1.18
      See Also:

    • createForDelimitedStringArrays

      public static BinaryTable.ColumnDesc createForDelimitedStringArrays(byte delim) throws FitsException
      Creates a new column descriptor for variable-length arrays of delimited string entries.
      Parameters:
      delim - the byte value that delimits strings that are shorter than the storage length. It should be in the ASCII range of 0x20 through 0x7e.
      Returns:
      the new column descriptor
      Throws:
      FitsException - if the column could not be created.
      Since:
      1.18
      See Also:

    • createForVariableSize

      public static BinaryTable.ColumnDesc createForVariableSize(Class<?> type) throws FitsException
      Creates a new column descriptor for variable length 1D arrays or strings. The type may be any primitive type, or else String.class, Boolean.class (for FITS logicals), ComplexValue.class or ComplexValue.Float.class (for complex values with 64-bit and 32-bit precision, respectively). Whereas Boolean type columns will be stored as FITS logicals (1 element per byte), boolean types will be stored as packed bits (with up to 8 elements per byte).
      Parameters:
      type - The Java type of base elements that this column is designated to contain. For example int.class if the column will contain integers or arrays of integers.
      Returns:
      the new column descriptor
      Throws:
      FitsException - if the base type is not one that can be used in binary table columns.
      Since:
      1.18
      See Also:

    • clone

      public BinaryTable.ColumnDesc clone()

    • isSingleton

      public final boolean isSingleton()
      Checks if this column contains single (scalar / non-array) elements only, including single strings or single complex values.
      Returns:
      true if the column contains individual elements of its type, or else false if it contains arrays.
      Since:
      1.18

    • isLogical

      public final boolean isLogical()
      Checks if this column contains logical values. FITS logicals can each hve true, false or null (undefined) values. It is the support for these undefined values that set it apart from typical booleans. Also, logicals are stored as one byte per element. So if using only true, false values without null bits will offer more compact storage (by up to a factor of 8). You can convert existing logical columns to bits via BinaryTable.convertToBits(int).
      Returns:
      true if this column contains logical values.
      Since:
      1.18
      See Also:

    • isBits

      public final boolean isBits()
      Checks if this column contains only true boolean values (bits). Unlike logicals, bits can have only true, false values with no support for null , but offer more compact storage (by up to a factor of 8) than logicals. You can convert existing logical columns to bits via BinaryTable.convertToBits(int).
      Returns:
      true if this column contains true / false bits only.
      Since:
      1.18
      See Also:

    • isString

      public final boolean isString()
      Checks if this column stores ASCII strings.
      Returns:
      true if this column contains only strings.
      See Also:

    • isComplex

      public final boolean isComplex()
      Checks if this column contains complex values. You can convert suitable columns of float or double elements to complex using BinaryTable.setComplexColumn(int), as long as the last dimension is 2, ir if the variable-length columns contain even-number of values exclusively.
      Returns:
      true if this column contains complex values.

    • isNumeric

      public final boolean isNumeric()
      Checks if this column contains numerical values, such as any primitive number type (e.g. nt.class or double.class) or else a ComplexValue type. type.
      Returns:
      true if this column contains numerical data, including complex-valued data. String, bits, and FITS logicals are not numerical (but all other column types are).
      Since:
      1.20

    • getBase

      public Class<?> getBase()
      Deprecated.
      Ambiguous, use getLegacyBase() instead. It can be confusing since it is not clear if it refers to array element types used in FITS storage or on the java side when using the older array access, or if it refers to the class of entries in the main table, which may be heap pointers. It is also distinct from getElementClass(), which returns the boxed type used by BinaryTable.get(int, int) or BinaryTable.set(int, int, Object).
      Returns the Java array element type that is used in Java to represent data in this column. When accessing columns or their elements in the old way, through arrays, this is the type that arrays from the Java side will expect or provide. For example, when storing String values (regular or variable-sized), this will return String.class. Arrays returned by BinaryTable.getColumn(int), BinaryTable.getRow(int), and BinaryTable.getElement(int, int) will return arrays of this type, and the equivalent methods for setting data will expect arrays of this type as their argument.
      Returns:
      the Java class, arrays of which, packaged data for this column on the Java side.

    • getLegacyBase

      public Class<?> getLegacyBase()

      Returns the Java array element type that is used in Java to represent data in this column for the legacy table access methods. When accessing columns or their elements in the old way, through arrays, this is the type that arrays from the Java side will expect or provide. For example, when storing complex values (regular or variable-sized), this will return float.class or double.class. Arrays returned by BinaryTable.getColumn(int), BinaryTable.getRow(int), and BinaryTable.getElement(int, int) will return arrays of this type.

      This is different from getElementClass(), which in turn returns the boxed type of objects returned by BinaryTable.get(int, int).

      Returns:
      the Java class, arrays of which, packaged data for this column on the Java side.
      Since:
      1.18
      See Also:

    • getDimens

      public int[] getDimens()
      Deprecated.
      (for internal use) Use getEntryShape() instead. Not useful to users since it returns the dimensions of the primitive storage types, which is not always the dimension of table entries on the Java side.
      Returns the dimensions of elements in this column. As of 1.18, this method returns a copy ot the array used internally, which is safe to modify.
      Returns:
      an array with the element dimensions.

    • getElementClass

      public final Class<?> getElementClass()
      Returns the boxed Java type of elements stored in a column.
      Returns:
      The java type of elements in the columns. For columns containing strings, FITS logicals, or complex values it will be String.class, Boolean.class or ComplexValue.class respectively. For all other column types the primitive class of the elements contained (e.g. char.class, float.class) is returned.
      Since:
      1.18
      See Also:

    • getEntryDimension

      public final int getEntryDimension()
      Returns the dimensionality of the 'boxed' elements as returned by BinaryTable.get(int, int) or expected by BinaryTable.set(int, int, Object). That is it returns the dimnesion of 'boxed' elements, such as strings or complex values, rather than the dimension of characters or real components stored in the FITS for these.
      Returns:
      the number of array dimensions in the 'boxed' Java type for this column. Variable-sized columns will always return 1.
      Since:
      1.18
      See Also:

    • getEntryShape

      public final int[] getEntryShape()
      Returns the array shape of the 'boxed' elements as returned by BinaryTable.get(int, int) or expected by BinaryTable.set(int, int, Object). That is it returns the array shape of 'boxed' elements, such as strings or complex values, rather than the shape of characters or real components stored in the FITS for these.
      Returns:
      the array sized along each of the dimensions in the 'boxed' Java type for this column, or null if the data is stored as variable-sized one-dimensional arrays of the boxed element type. (Note, that accordingly variable-length string columns containing single strings will thus return {1}, not null).
      Since:
      1.18
      See Also:

    • getElementWidth

      public final int getElementWidth()
      Returns the number of primitive elements (sych as bytes) that constitute a Java element (such as a String) in this table.
      Returns:
      The number of primitives per Java element in the column, that is 1 for columns of primitive types, 2 for complex-valued columns, or the number of bytes (characters) in a String element. Variable-length strings will return -1.
      Since:
      1.18
      See Also:

    • getElementCount

      public final int getElementCount()
      Returns the number of 'boxed' elements as returned by BinaryTable.get(int, int) or expected by BinaryTable.set(int, int, Object). That is it returns the number of strings or complex values per table entry, rather than the number of of characters or real components stored in the FITS for these.
      Returns:
      the number of array elements in the 'boxed' Java type for this column, or -1 if the column contains elements of varying size.
      Since:
      1.18
      See Also:

    • getTableBaseCount

      public final int getTableBaseCount()
      Returns the number of regular primitive table elements in this column. For example, variable-length columns will always return 2, and complex-valued columns will return twice the number of complex values stored in each table entry.
      Returns:
      the number of primitive table elements
      Since:
      1.18

    • isVariableSize

      public final boolean isVariableSize()
      Checks if this column contains entries of different size. Data for variable length coulmns is stored on the heap as one-dimemnsional arrays. As such information about the 'shape' of data is lost when they are stored that way.
      Returns:
      true if the column contains elements of variable size, or else false if all entries have the same size and shape.

    • newInstance

      public Object newInstance(int nRow)
      Deprecated.
      (for internal use) This method should be private in the future.
      Parameters:
      nRow - the number of rows to allocate the array for
      Returns:
      new instance of the array with space for the specified number of rows.

    • rowLen

      public int rowLen()
      Deprecated.
      (for internal use) It may be reduced to private visibility in the future. Returns the number of bytes that each element occupies in its FITS serialized form in the stored row data.
      Returns:
      the number of bytes an element occupies in the FITS binary table data representation

    • hasLongPointers

      public boolean hasLongPointers()
      Checks if this column used 64-bit heap pointers.
      Returns:
      true if the column uses 64-bit heap pointers, otherwise false
      Since:
      1.18
      See Also: