Package nom.tam.util

Class FitsEncoder

Direct Known Subclasses:
BufferEncoder

public class FitsEncoder extends OutputEncoder
Encodes select Java arrays into FITS binary format (primarily for internal use)
Since:
1.16
See Also:
  • Constructor Details

    • FitsEncoder

      protected FitsEncoder()
      Instantiates a new encoder from Java arrays to FITS binary output. To be used by subclass constructors only.
    • FitsEncoder

      public FitsEncoder(OutputWriter o)
      Instantiates a new FITS binary data encoder for converting Java arrays into FITS data representations
      Parameters:
      o - the FITS output.
  • Method Details

    • byteForBoolean

      public static byte byteForBoolean(Boolean b)
      Returns the FITS byte value representing a logical value. This call supports null values, which are allowed by the FITS standard. FITS defines 'T' as true, 'F' as false, and 0 as null. Prior versions of this library have used the value 1 for true, and 0 for false. Therefore, this implementation will recognise both 'T' and 1 as true, but 0 will map to null and everything else will return false.
      Parameters:
      b - A java boolean value or null
      Returns:
      the FITS byte representation of a boolean value.
    • writeBoolean

      @Deprecated protected void writeBoolean(Boolean b) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      b - a boolean value or null.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeChar

      @Deprecated protected void writeChar(int c) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      c - An ASCII character.
      Throws:
      IOException - if there was an IO error writing to the output.
    • write

      protected void write(boolean[] b, int start, int length) throws IOException
      See ArrayDataOutput.write(boolean[], int, int) for the general contract of this method. In FITS, true values are represented by the ASCII byte for 'T', whereas false is represented by the ASCII byte for 'F'.
      Parameters:
      b - array of booleans.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(Boolean[] b, int start, int length) throws IOException
      See ArrayDataOutput.write(Boolean[], int, int) for the general contract of this method. In FITS, true values are represented by the ASCII byte for 'T', false is represented by the ASCII byte for 'F', while null values are represented by the value 0.
      Parameters:
      b - array of booleans.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • writeByte

      @Deprecated protected void writeByte(int b) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      b - a single byte.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeShort

      @Deprecated protected void writeShort(int s) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      s - a 16-bit integer value.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeInt

      @Deprecated protected void writeInt(int i) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      i - a 32-bit integer value.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeLong

      @Deprecated protected void writeLong(long l) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      l - a 64-bit integer value.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeFloat

      @Deprecated protected void writeFloat(float f) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally by this library only.
      Parameters:
      f - a single-precision (32-bit) floating point value.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeDouble

      @Deprecated protected void writeDouble(double d) throws IOException
      Deprecated.
      (for internal use) Low-level reading/writing should be handled internally as arrays by this library only.
      Parameters:
      d - a double-precision (64-bit) floating point value.
      Throws:
      IOException - if there was an IO error writing to the output.
    • writeBytes

      protected void writeBytes(String s) throws IOException
      Writes a Java string as a sequence of ASCII bytes to the output. FITS does not support unicode characters in its version of strings (character arrays), but instead it is restricted to the ASCII set of 1-byte characters.
      Parameters:
      s - the Java string
      Throws:
      IOException - if the string could not be fully written to the output
      See Also:
    • writeChars

      protected void writeChars(String s) throws IOException
      In FITS characters are usually represented as 1-byte ASCII, not as the 2-byte Java types. However, previous implementations if this library have erroneously written 2-byte characters into the FITS. For compatibility both the FITS standard of 1-byte ASCII and the old 2-byte behaviour are supported, and can be selected via FitsFactory.setUseUnicodeChars(boolean).
      Parameters:
      s - a string containing ASCII-only characters
      Throws:
      IOException - if there was an IO error writing all the characters to the output.
      See Also:
    • write

      protected void write(char[] c, int start, int length) throws IOException
      See ArrayDataOutput.write(char[], int, int) for the general contract of this method. In FITS characters are usually represented as 1-byte ASCII, not as the 2-byte Java types. However, previous implementations if this library have erroneously written 2-byte characters into the FITS. For compatibility both the FITS standard of 1-byte ASCII and the old 2-byte behaviour are supported, and can be selected via FitsFactory.setUseUnicodeChars(boolean).
      Parameters:
      c - array of character (ASCII only is supported).
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
      See Also:
    • write

      protected void write(short[] s, int start, int length) throws IOException
      See ArrayDataOutput.write(short[], int, int) for a contract of this method.
      Parameters:
      s - array of 16-bit integers.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(int[] i, int start, int length) throws IOException
      See ArrayDataOutput.write(int[], int, int) for a contract of this method.
      Parameters:
      i - array of 32-bit integers.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(long[] l, int start, int length) throws IOException
      See ArrayDataOutput.write(long[], int, int) for a contract of this method.
      Parameters:
      l - array of 64-bit integers.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(float[] f, int start, int length) throws IOException
      See ArrayDataOutput.write(float[], int, int) for a contract of this method.
      Parameters:
      f - array of single precision (32-bit) floating point values.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(double[] d, int start, int length) throws IOException
      See ArrayDataOutput.write(double[], int, int) for a contract of this method.
      Parameters:
      d - array of double-precision (64-bit) floating point values.
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • write

      protected void write(String[] str, int start, int length) throws IOException
      See ArrayDataOutput.write(String[], int, int) for a contract of this method.
      Parameters:
      str - array of strings (containing ASCII characters only).
      start - the index of the first element in the array to write
      length - number of array elements to write
      Throws:
      IOException - if there was an IO error writing to the output
    • writeArray

      public void writeArray(Object o) throws IOException, IllegalArgumentException
      Description copied from class: OutputEncoder
      Writes the contents of a Java array to the output translating the data to the required binary representation. The argument may be any generic Java array, including heterogeneous arrays of arrays.
      Specified by:
      writeArray in class OutputEncoder
      Parameters:
      o - the Java array, including heterogeneous arrays of arrays. If null nothing will be written to the output.
      Throws:
      IOException - if there was an IO error writing to the output
      IllegalArgumentException - if the supplied object is not a Java array or if it contains Java types that are not supported by the decoder.
      See Also:
    • putArray

      protected void putArray(Object o) throws IOException, IllegalArgumentException

      Puts a Java array into the conversion buffer, but with no guarantee of flushing the conversion buffer to the underlying output. The argument may be any Java array of the types supported in FITS, including multi-dimensional arrays and heterogeneous arrays of arrays.

      The caller may put multiple data object into the conversion buffer before eventually calling OutputEncoder.flush() to ensure that everything is written to the output. Note, the this call may flush the contents of the conversion buffer to the output if it needs more conversion space than what is avaiable.

      Parameters:
      o - A Java array, including multi-dimensional arrays and heterogeneous arrays of arrays.
      Throws:
      IOException - if there was an IO error while trying to flush the conversion buffer to the stream before all elements were converted.
      IllegalArgumentException - if the argument is not an array, or if it is or contains an element that does not have a known FITS representation.
      See Also:
    • computeSize

      public static long computeSize(Object o)
      Returns the size of this object as the number of bytes in a FITS binary representation.
      Parameters:
      o - the object
      Returns:
      the number of bytes in the FITS binary representation of the object or 0 if the object has no FITS representation. (Also elements not known to FITS will count as 0 sized).