org.apache.poi.util

## Class LittleEndian

- java.lang.Object
- - org.apache.poi.util.LittleEndian

- All Implemented Interfaces:
    LittleEndianConsts

      public class LittleEndian
      extends java.lang.Object
      implements LittleEndianConsts

  a utility class for handling little-endian numbers, which the 80x86 world is replete with. The methods are all static, and input/output is from/to byte arrays, or from InputStreams.
  Author:
    Marc Johnson (mjohnson at apache dot org), Andrew Oliver (acoliver at apache dot org)

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `LittleEndian.BufferUnderrunException` Exception to handle buffer underruns

  - ### Field Summary

    - ### Fields inherited from interface org.apache.poi.util.LittleEndianConsts

      `BYTE_SIZE, DOUBLE_SIZE, INT_SIZE, LONG_SIZE, SHORT_SIZE`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static byte[]` | `getByteArray(byte[] data, int offset, int size)` Copy a portion of a byte array
    `static byte[]` | `getByteArray(byte[] data, int offset, int size, int maxSize)` Copy a portion of a byte array
    `static double` | `getDouble(byte[] data)` get a double value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java double
    `static double` | `getDouble(byte[] data, int offset)` get a double value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java double
    `static float` | `getFloat(byte[] data)` get a float value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java float
    `static float` | `getFloat(byte[] data, int offset)` get a float value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java float
    `static int` | `getInt(byte[] data)` get an int value from the beginning of a byte array
    `static int` | `getInt(byte[] data, int offset)` get an int value from a byte array
    `static long` | `getLong(byte[] data)` get a long value from a byte array
    `static long` | `getLong(byte[] data, int offset)` get a long value from a byte array
    `static short` | `getShort(byte[] data)` get a short value from the beginning of a byte array
    `static short` | `getShort(byte[] data, int offset)` get a short value from a byte array
    `static short[]` | `getShortArray(byte[] data, int offset, int size)` Read short array
    `static short` | `getUByte(byte[] data)` get the unsigned value of a byte.
    `static short` | `getUByte(byte[] data, int offset)` get the unsigned value of a byte.
    `static long` | `getUInt(byte[] data)` get an unsigned int value from a byte array
    `static long` | `getUInt(byte[] data, int offset)` get an unsigned int value from a byte array
    `static int` | `getUShort(byte[] data)` get an unsigned short value from the beginning of a byte array
    `static int` | `getUShort(byte[] data, int offset)` get an unsigned short value from a byte array
    `static void` | `putByte(byte[] data, int offset, int value)` executes:
    `static void` | `putDouble(byte[] data, int offset, double value)` put a double value into a byte array
    `static void` | `putDouble(double value, java.io.OutputStream outputStream)` put a double value into a byte array
    `static void` | `putFloat(byte[] data, int offset, float value)` put a float value into a byte array
    `static void` | `putFloat(float value, java.io.OutputStream outputStream)` put a float value into a byte array
    `static void` | `putInt(byte[] data, int offset, int value)` put an int value into a byte array
    `static void` | `putInt(int value, java.io.OutputStream outputStream)` Put int into output stream
    `static void` | `putLong(byte[] data, int offset, long value)` put a long value into a byte array
    `static void` | `putLong(long value, java.io.OutputStream outputStream)` Put long into output stream
    `static void` | `putShort(byte[] data, int offset, short value)` put a short value into a byte array
    `static void` | `putShort(java.io.OutputStream outputStream, short value)` Put signed short into output stream
    `static void` | `putShortArray(byte[] data, int startOffset, short[] value)` Stores short array in buffer
    `static void` | `putUByte(byte[] data, int offset, short value)` put an unsigned byte value into a byte array
    `static void` | `putUInt(byte[] data, int offset, long value)` put an unsigned int value into a byte array
    `static void` | `putUInt(long value, java.io.OutputStream outputStream)` Put unsigned int into output stream
    `static void` | `putUShort(byte[] data, int offset, int value)` put an unsigned short value into a byte array
    `static void` | `putUShort(int value, java.io.OutputStream outputStream)` Put unsigned short into output stream
    `static int` | `readInt(java.io.InputStream stream)` get an int value from an InputStream
    `static long` | `readLong(java.io.InputStream stream)` get a long value from an InputStream
    `static short` | `readShort(java.io.InputStream stream)` get a short value from an InputStream
    `static long` | `readUInt(java.io.InputStream stream)` get an unsigned int value from an InputStream
    `static int` | `readUShort(java.io.InputStream stream)`
    `static int` | `ubyteToInt(byte b)` Convert an 'unsigned' byte to an integer.

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

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

- - ### Method Detail

    - #### getByteArray

          public static byte[] getByteArray(byte[] data,
                                            int offset,
                                            int size)

      Copy a portion of a byte array
      Parameters:
        `data` - the original byte array
        `offset` - Where to start copying from.
        `size` - Number of bytes to copy.
      Returns:
        The byteArray value
      Throws:
        `java.lang.IndexOutOfBoundsException` - - if copying would cause access of data outside array bounds.
      See Also:
        `if size is not a constant`

    - #### getByteArray

          public static byte[] getByteArray(byte[] data,
                                            int offset,
                                            int size,
                                            int maxSize)

      Copy a portion of a byte array
      Parameters:
        `data` - the original byte array
        `offset` - Where to start copying from.
        `size` - Number of bytes to copy.
        `maxSize` - Size must be <= maxSize or an exception is thrown. Use this to avoid potential OOMs on corrupt data.
      Returns:
        The byteArray value
      Throws:
        `java.lang.IndexOutOfBoundsException` - - if copying would cause access of data outside array bounds.

    - #### getDouble

          public static double getDouble(byte[] data)

      get a double value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java double
      Parameters:
        `data` - the byte array
      Returns:
        the double (64-bit) value

    - #### getDouble

          public static double getDouble(byte[] data,
                                         int offset)

      get a double value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java double
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the double (64-bit) value

    - #### getFloat

          public static float getFloat(byte[] data)

      get a float value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java float
      Parameters:
        `data` - the byte array
      Returns:
        the double (64-bit) value

    - #### getFloat

          public static float getFloat(byte[] data,
                                       int offset)

      get a float value from a byte array, reads it in little endian format then converts the resulting revolting IEEE 754 (curse them) floating point number to a happy java float
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the double (64-bit) value

    - #### getInt

          public static int getInt(byte[] data)

      get an int value from the beginning of a byte array
      Parameters:
        `data` - the byte array
      Returns:
        the int (32-bit) value

    - #### getInt

          public static int getInt(byte[] data,
                                   int offset)

      get an int value from a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the int (32-bit) value

    - #### getLong

          public static long getLong(byte[] data)

      get a long value from a byte array
      Parameters:
        `data` - the byte array
      Returns:
        the long (64-bit) value

    - #### getLong

          public static long getLong(byte[] data,
                                     int offset)

      get a long value from a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the long (64-bit) value

    - #### getShort

          public static short getShort(byte[] data)

      get a short value from the beginning of a byte array
      Parameters:
        `data` - the byte array
      Returns:
        the short (16-bit) value

    - #### getShort

          public static short getShort(byte[] data,
                                       int offset)

      get a short value from a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the short (16-bit) value

    - #### getShortArray

          public static short[] getShortArray(byte[] data,
                                              int offset,
                                              int size)

      Read short array
      Parameters:
        `data` - the original byte array
        `offset` - Where to start copying from.
        `size` - Number of bytes to copy.
      Throws:
        `java.lang.IndexOutOfBoundsException` - - if read would cause access of data outside array bounds.

    - #### getUByte

          public static short getUByte(byte[] data)

      get the unsigned value of a byte.
      Parameters:
        `data` - the byte array.
      Returns:
        the unsigned value of the byte as a 16 bit short

    - #### getUByte

          public static short getUByte(byte[] data,
                                       int offset)

      get the unsigned value of a byte.
      Parameters:
        `data` - the byte array.
        `offset` - a starting offset into the byte array.
      Returns:
        the unsigned value of the byte as a 16 bit short

    - #### getUInt

          public static long getUInt(byte[] data)

      get an unsigned int value from a byte array
      Parameters:
        `data` - the byte array
      Returns:
        the unsigned int (32-bit) value in a long

    - #### getUInt

          public static long getUInt(byte[] data,
                                     int offset)

      get an unsigned int value from a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the unsigned int (32-bit) value in a long

    - #### getUShort

          public static int getUShort(byte[] data)

      get an unsigned short value from the beginning of a byte array
      Parameters:
        `data` - the byte array
      Returns:
        the unsigned short (16-bit) value in an int

    - #### getUShort

          public static int getUShort(byte[] data,
                                      int offset)

      get an unsigned short value from a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
      Returns:
        the unsigned short (16-bit) value in an integer

    - #### putByte

          public static void putByte(byte[] data,
                                     int offset,
                                     int value)

      executes:

      `data[offset] = (byte)value;`

      Added for consistency with other put~() methods

    - #### putDouble

          public static void putDouble(byte[] data,
                                       int offset,
                                       double value)

      put a double value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the double (64-bit) value

    - #### putDouble

          public static void putDouble(double value,
                                       java.io.OutputStream outputStream)
                                throws java.io.IOException

      put a double value into a byte array
      Parameters:
        `value` - the double (64-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putFloat

          public static void putFloat(byte[] data,
                                      int offset,
                                      float value)

      put a float value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the float (32-bit) value

    - #### putFloat

          public static void putFloat(float value,
                                      java.io.OutputStream outputStream)
                               throws java.io.IOException

      put a float value into a byte array
      Parameters:
        `value` - the float (32-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putInt

          public static void putInt(byte[] data,
                                    int offset,
                                    int value)

      put an int value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the int (32-bit) value

    - #### putInt

          public static void putInt(int value,
                                    java.io.OutputStream outputStream)
                             throws java.io.IOException

      Put int into output stream
      Parameters:
        `value` - the int (32-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putLong

          public static void putLong(byte[] data,
                                     int offset,
                                     long value)

      put a long value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the long (64-bit) value

    - #### putLong

          public static void putLong(long value,
                                     java.io.OutputStream outputStream)
                              throws java.io.IOException

      Put long into output stream
      Parameters:
        `value` - the long (64-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putShort

          public static void putShort(byte[] data,
                                      int offset,
                                      short value)

      put a short value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the short (16-bit) value

    - #### putShort

          public static void putShort(java.io.OutputStream outputStream,
                                      short value)
                               throws java.io.IOException

      Put signed short into output stream
      Parameters:
        `value` - the short (16-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putShortArray

          public static void putShortArray(byte[] data,
                                           int startOffset,
                                           short[] value)

      Stores short array in buffer
      Parameters:
        `data` - the byte array
        `startOffset` - a starting offset into the byte array
        `value` - the short (16-bit) values

    - #### putUByte

          public static void putUByte(byte[] data,
                                      int offset,
                                      short value)

      put an unsigned byte value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the short (16-bit) value
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - may be thrown

    - #### putUInt

          public static void putUInt(byte[] data,
                                     int offset,
                                     long value)

      put an unsigned int value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the int (32-bit) value
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - may be thrown

    - #### putUInt

          public static void putUInt(long value,
                                     java.io.OutputStream outputStream)
                              throws java.io.IOException

      Put unsigned int into output stream
      Parameters:
        `value` - the int (32-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### putUShort

          public static void putUShort(byte[] data,
                                       int offset,
                                       int value)

      put an unsigned short value into a byte array
      Parameters:
        `data` - the byte array
        `offset` - a starting offset into the byte array
        `value` - the short (16-bit) value
      Throws:
        `java.lang.ArrayIndexOutOfBoundsException` - may be thrown

    - #### putUShort

          public static void putUShort(int value,
                                       java.io.OutputStream outputStream)
                                throws java.io.IOException

      Put unsigned short into output stream
      Parameters:
        `value` - the unsigned short (16-bit) value
        `outputStream` - output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readInt

          public static int readInt(java.io.InputStream stream)
                             throws java.io.IOException,
                                    LittleEndian.BufferUnderrunException

      get an int value from an InputStream
      Parameters:
        `stream` - the InputStream from which the int is to be read
      Returns:
        the int (32-bit) value
      Throws:
        `java.io.IOException` - will be propagated back to the caller
        `LittleEndian.BufferUnderrunException` - if the stream cannot provide enough bytes

    - #### readUInt

          public static long readUInt(java.io.InputStream stream)
                               throws java.io.IOException,
                                      LittleEndian.BufferUnderrunException

      get an unsigned int value from an InputStream
      Parameters:
        `stream` - the InputStream from which the int is to be read
      Returns:
        the unsigned int (32-bit) value
      Throws:
        `java.io.IOException` - will be propagated back to the caller
        `LittleEndian.BufferUnderrunException` - if the stream cannot provide enough bytes

    - #### readLong

          public static long readLong(java.io.InputStream stream)
                               throws java.io.IOException,
                                      LittleEndian.BufferUnderrunException

      get a long value from an InputStream
      Parameters:
        `stream` - the InputStream from which the long is to be read
      Returns:
        the long (64-bit) value
      Throws:
        `java.io.IOException` - will be propagated back to the caller
        `LittleEndian.BufferUnderrunException` - if the stream cannot provide enough bytes

    - #### readShort

          public static short readShort(java.io.InputStream stream)
                                 throws java.io.IOException,
                                        LittleEndian.BufferUnderrunException

      get a short value from an InputStream
      Parameters:
        `stream` - the InputStream from which the short is to be read
      Returns:
        the short (16-bit) value
      Throws:
        `java.io.IOException` - will be propagated back to the caller
        `LittleEndian.BufferUnderrunException` - if the stream cannot provide enough bytes

    - #### readUShort

          public static int readUShort(java.io.InputStream stream)
                                throws java.io.IOException,
                                       LittleEndian.BufferUnderrunException

      Throws:
        `java.io.IOException`
        `LittleEndian.BufferUnderrunException`

    - #### ubyteToInt

          public static int ubyteToInt(byte b)

      Convert an 'unsigned' byte to an integer. ie, don't carry across the sign.
      Parameters:
        `b` - Description of the Parameter
      Returns:
        Description of the Return Value

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.