Package org.apache.commons.io

# Class EndianUtils

java.lang.Object
org.apache.commons.io.EndianUtils

public class EndianUtils extends Object
Helps with reading and writing primitive numeric types (`short`, `int`, `long`, `float`, and `double`) that are encoded in little-endian using two's complement or unsigned representations.

Different computer architectures have different conventions for byte ordering. In "Little Endian" architectures (e.g. X86), the low-order byte is stored in memory at the lowest address, and subsequent bytes at higher addresses. In "Big Endian" architectures (e.g. Motorola 680X0), the situation is reversed. Most methods and classes throughout Java — e.g. `DataInputStream` and `Double.longBitsToDouble()` — assume data is laid out in big-endian order with the most significant byte first. The methods in this class read and write data in little-endian order, generally by reversing the bytes and then using the regular Java methods to convert the swapped bytes to a primitive type.

Provenance: Excalibur

See Also:
  - `SwappedDataInputStream`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `EndianUtils()`
  Deprecated.
  TODO Make private in 3.0.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static double`
  `readSwappedDouble(byte[] data, int offset)`
  Reads a little-endian `double` value from a byte array at a given offset.
  `static double`
  `readSwappedDouble(InputStream input)`
  Reads a little-endian `double` value from an InputStream.
  `static float`
  `readSwappedFloat(byte[] data, int offset)`
  Reads a little-endian `float` value from a byte array at a given offset.
  `static float`
  `readSwappedFloat(InputStream input)`
  Reads a little-endian `float` value from an InputStream.
  `static int`
  `readSwappedInteger(byte[] data, int offset)`
  Reads a little-endian `int` value from a byte array at a given offset.
  `static int`
  `readSwappedInteger(InputStream input)`
  Reads a little-endian `int` value from an InputStream.
  `static long`
  `readSwappedLong(byte[] data, int offset)`
  Reads a little-endian `long` value from a byte array at a given offset.
  `static long`
  `readSwappedLong(InputStream input)`
  Reads a little-endian `long` value from an InputStream.
  `static short`
  `readSwappedShort(byte[] data, int offset)`
  Reads a little-endian `short` value from a byte array at a given offset.
  `static short`
  `readSwappedShort(InputStream input)`
  Reads a little-endian `short` value from an InputStream.
  `static long`
  `readSwappedUnsignedInteger(byte[] data, int offset)`
  Reads a little-endian unsigned integer (32-bit) value from a byte array at a given offset.
  `static long`
  `readSwappedUnsignedInteger(InputStream input)`
  Reads a little-endian unsigned integer (32-bit) from an InputStream.
  `static int`
  `readSwappedUnsignedShort(byte[] data, int offset)`
  Reads an unsigned short (16-bit) value from a byte array in little-endian order at a given offset.
  `static int`
  `readSwappedUnsignedShort(InputStream input)`
  Reads an unsigned short (16-bit) from an InputStream in little-endian order.
  `static double`
  `swapDouble(double value)`
  Converts a `double` value from big-endian to little-endian and vice versa.
  `static float`
  `swapFloat(float value)`
  Converts a `float` value from big-endian to little-endian and vice versa.
  `static int`
  `swapInteger(int value)`
  Converts an `int` value from big-endian to little-endian and vice versa.
  `static long`
  `swapLong(long value)`
  Converts a `long` value from big-endian to little-endian and vice versa.
  `static short`
  `swapShort(short value)`
  Converts a `short` value from big-endian to little-endian and vice versa.
  `static void`
  `writeSwappedDouble(byte[] data, int offset, double value)`
  Writes the 8 bytes of a `double` to a byte array at a given offset in little-endian order.
  `static void`
  `writeSwappedDouble(OutputStream output, double value)`
  Writes the 8 bytes of a `double` to an output stream in little-endian order.
  `static void`
  `writeSwappedFloat(byte[] data, int offset, float value)`
  Writes the 4 bytes of a `float` to a byte array at a given offset in little-endian order.
  `static void`
  `writeSwappedFloat(OutputStream output, float value)`
  Writes the 4 bytes of a `float` to an output stream in little-endian order.
  `static void`
  `writeSwappedInteger(byte[] data, int offset, int value)`
  Writes the 4 bytes of an `int` to a byte array at a given offset in little-endian order.
  `static void`
  `writeSwappedInteger(OutputStream output, int value)`
  Writes the 4 bytes of an `int` to an output stream in little-endian order.
  `static void`
  `writeSwappedLong(byte[] data, int offset, long value)`
  Writes the 8 bytes of a `long` to a byte array at a given offset in little-endian order.
  `static void`
  `writeSwappedLong(OutputStream output, long value)`
  Writes the 8 bytes of a `long` to an output stream in little-endian order.
  `static void`
  `writeSwappedShort(byte[] data, int offset, short value)`
  Writes the 2 bytes of a `short` to a byte array at a given offset in little-endian order.
  `static void`
  `writeSwappedShort(OutputStream output, short value)`
  Writes the 2 bytes of a `short` to an output stream using little-endian encoding.

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

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

- ## Constructor Details

  - ### EndianUtils

    @Deprecated public EndianUtils()
    Deprecated.
    TODO Make private in 3.0.
    Instances should NOT be constructed in standard programming.

- ## Method Details

  - ### readSwappedDouble

    public static double readSwappedDouble(byte[] data, int offset)
    Reads a little-endian `double` value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 8 bytes.

  - ### readSwappedDouble

    public static double readSwappedDouble(InputStream input) throws IOException
    Reads a little-endian `double` value from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedFloat

    public static float readSwappedFloat(byte[] data, int offset)
    Reads a little-endian `float` value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 4 bytes.

  - ### readSwappedFloat

    public static float readSwappedFloat(InputStream input) throws IOException
    Reads a little-endian `float` value from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedInteger

    public static int readSwappedInteger(byte[] data, int offset)
    Reads a little-endian `int` value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 4 bytes.

  - ### readSwappedInteger

    public static int readSwappedInteger(InputStream input) throws IOException
    Reads a little-endian `int` value from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedLong

    public static long readSwappedLong(byte[] data, int offset)
    Reads a little-endian `long` value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 8 bytes.

  - ### readSwappedLong

    public static long readSwappedLong(InputStream input) throws IOException
    Reads a little-endian `long` value from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedShort

    public static short readSwappedShort(byte[] data, int offset)
    Reads a little-endian `short` value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 2 bytes.

  - ### readSwappedShort

    public static short readSwappedShort(InputStream input) throws IOException
    Reads a little-endian `short` value from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedUnsignedInteger

    public static long readSwappedUnsignedInteger(byte[] data, int offset)
    Reads a little-endian unsigned integer (32-bit) value from a byte array at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 4 bytes.

  - ### readSwappedUnsignedInteger

    public static long readSwappedUnsignedInteger(InputStream input) throws IOException
    Reads a little-endian unsigned integer (32-bit) from an InputStream.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### readSwappedUnsignedShort

    public static int readSwappedUnsignedShort(byte[] data, int offset)
    Reads an unsigned short (16-bit) value from a byte array in little-endian order at a given offset.
    Parameters:
      `data` - source byte array.
      `offset` - starting offset in the byte array.
    Returns:
      the value read.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 2 bytes.

  - ### readSwappedUnsignedShort

    public static int readSwappedUnsignedShort(InputStream input) throws IOException
    Reads an unsigned short (16-bit) from an InputStream in little-endian order.
    Parameters:
      `input` - source InputStream.
    Returns:
      the value just read.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### swapDouble

    public static double swapDouble(double value)
    Converts a `double` value from big-endian to little-endian and vice versa. That is, it converts the `double` to bytes, reverses the bytes, and then reinterprets those bytes as a new `double`. This can be useful if you have a number that was read from the underlying source in the wrong endianness.
    Parameters:
      `value` - value to convert.
    Returns:
      the converted value.

  - ### swapFloat

    public static float swapFloat(float value)
    Converts a `float` value from big-endian to little-endian and vice versa.
    Parameters:
      `value` - value to convert.
    Returns:
      the converted value.

  - ### swapInteger

    public static int swapInteger(int value)
    Converts an `int` value from big-endian to little-endian and vice versa.
    Parameters:
      `value` - value to convert.
    Returns:
      the converted value.

  - ### swapLong

    public static long swapLong(long value)
    Converts a `long` value from big-endian to little-endian and vice versa.
    Parameters:
      `value` - value to convert.
    Returns:
      the converted value.

  - ### swapShort

    public static short swapShort(short value)
    Converts a `short` value from big-endian to little-endian and vice versa.
    Parameters:
      `value` - value to convert.
    Returns:
      the converted value.

  - ### writeSwappedDouble

    public static void writeSwappedDouble(byte[] data, int offset, double value)
    Writes the 8 bytes of a `double` to a byte array at a given offset in little-endian order.
    Parameters:
      `data` - target byte array.
      `offset` - starting offset in the byte array.
      `value` - value to write.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 8 bytes.

  - ### writeSwappedDouble

    public static void writeSwappedDouble(OutputStream output, double value) throws IOException
    Writes the 8 bytes of a `double` to an output stream in little-endian order.
    Parameters:
      `output` - target OutputStream.
      `value` - value to write.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### writeSwappedFloat

    public static void writeSwappedFloat(byte[] data, int offset, float value)
    Writes the 4 bytes of a `float` to a byte array at a given offset in little-endian order.
    Parameters:
      `data` - target byte array.
      `offset` - starting offset in the byte array.
      `value` - value to write.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 4 bytes.

  - ### writeSwappedFloat

    public static void writeSwappedFloat(OutputStream output, float value) throws IOException
    Writes the 4 bytes of a `float` to an output stream in little-endian order.
    Parameters:
      `output` - target OutputStream.
      `value` - value to write.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### writeSwappedInteger

    public static void writeSwappedInteger(byte[] data, int offset, int value)
    Writes the 4 bytes of an `int` to a byte array at a given offset in little-endian order.
    Parameters:
      `data` - target byte array.
      `offset` - starting offset in the byte array.
      `value` - value to write.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 4 bytes.

  - ### writeSwappedInteger

    public static void writeSwappedInteger(OutputStream output, int value) throws IOException
    Writes the 4 bytes of an `int` to an output stream in little-endian order.
    Parameters:
      `output` - target OutputStream.
      `value` - value to write.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### writeSwappedLong

    public static void writeSwappedLong(byte[] data, int offset, long value)
    Writes the 8 bytes of a `long` to a byte array at a given offset in little-endian order.
    Parameters:
      `data` - target byte array.
      `offset` - starting offset in the byte array.
      `value` - value to write.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 8 bytes.

  - ### writeSwappedLong

    public static void writeSwappedLong(OutputStream output, long value) throws IOException
    Writes the 8 bytes of a `long` to an output stream in little-endian order.
    Parameters:
      `output` - target OutputStream.
      `value` - value to write.
    Throws:
      `IOException` - in case of an I/O problem.

  - ### writeSwappedShort

    public static void writeSwappedShort(byte[] data, int offset, short value)
    Writes the 2 bytes of a `short` to a byte array at a given offset in little-endian order.
    Parameters:
      `data` - target byte array.
      `offset` - starting offset in the byte array.
      `value` - value to write.
    Throws:
      `IllegalArgumentException` - if the part of the byte array starting at offset does not have at least 2 bytes.

  - ### writeSwappedShort

    public static void writeSwappedShort(OutputStream output, short value) throws IOException
    Writes the 2 bytes of a `short` to an output stream using little-endian encoding.
    Parameters:
      `output` - target OutputStream.
      `value` - value to write.
    Throws:
      `IOException` - in case of an I/O problem.