org.apache.commons.io

Class EndianUtils

java.lang.Object

org.apache.commons.io.EndianUtils

public class EndianUtils
extends java.lang.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 and Description
EndianUtils() Deprecated. TODO Make private in 3.0.

Method Summary

Modifier and Type	Method and Description
private static int	read(java.io.InputStream input) Reads the next byte from the input stream.
static double	readSwappedDouble(byte[] data, int offset) Reads a little endian double value from a byte array at a given offset.
static double	readSwappedDouble(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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.
private static void	validateByteArrayOffset(byte[] data, int offset, int byteNeeded) Validates if the provided byte array has enough data.
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(java.io.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(java.io.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(java.io.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(java.io.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(java.io.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 Detail

EndianUtils

@Deprecated
public EndianUtils()

Deprecated. TODO Make private in 3.0.

Instances should NOT be constructed in standard programming.

Method Detail

read

private static int read(java.io.InputStream input)
                 throws java.io.IOException

Reads the next byte from the input stream.

Parameters:

input - the stream

Returns:

the byte

Throws:

java.io.IOException - if the end of file is reached

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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 8 bytes

readSwappedDouble

public static double readSwappedDouble(java.io.InputStream input)
                                throws java.io.IOException

Reads a little endian double value from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 4 bytes

readSwappedFloat

public static float readSwappedFloat(java.io.InputStream input)
                              throws java.io.IOException

Reads a little endian float value from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 4 bytes

readSwappedInteger

public static int readSwappedInteger(java.io.InputStream input)
                              throws java.io.IOException

Reads a little endian int value from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 8 bytes

readSwappedLong

public static long readSwappedLong(java.io.InputStream input)
                            throws java.io.IOException

Reads a little endian long value from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 2 bytes

readSwappedShort

public static short readSwappedShort(java.io.InputStream input)
                              throws java.io.IOException

Reads a little endian short value from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 4 bytes

readSwappedUnsignedInteger

public static long readSwappedUnsignedInteger(java.io.InputStream input)
                                       throws java.io.IOException

Reads a little endian unsigned integer (32-bit) from an InputStream.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 2 bytes

readSwappedUnsignedShort

public static int readSwappedUnsignedShort(java.io.InputStream input)
                                    throws java.io.IOException

Reads an unsigned short (16-bit) from an InputStream in little endian order.

Parameters:

input - source InputStream

Returns:

the value just read

Throws:

java.io.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

validateByteArrayOffset

private static void validateByteArrayOffset(byte[] data,
                                            int offset,
                                            int byteNeeded)

Validates if the provided byte array has enough data.

Parameters:

data - the input byte array

offset - the input offset

byteNeeded - the needed number of bytes

Throws:

java.lang.IllegalArgumentException - if the byte array does not have enough data

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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 8 bytes

writeSwappedDouble

public static void writeSwappedDouble(java.io.OutputStream output,
                                      double value)
                               throws java.io.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:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 4 bytes

writeSwappedFloat

public static void writeSwappedFloat(java.io.OutputStream output,
                                     float value)
                              throws java.io.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:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 4 bytes

writeSwappedInteger

public static void writeSwappedInteger(java.io.OutputStream output,
                                       int value)
                                throws java.io.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:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 8 bytes

writeSwappedLong

public static void writeSwappedLong(java.io.OutputStream output,
                                    long value)
                             throws java.io.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:

java.io.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:

java.lang.IllegalArgumentException - if the part of the byte array starting at offset does not have at least 2 bytes

writeSwappedShort

public static void writeSwappedShort(java.io.OutputStream output,
                                     short value)
                              throws java.io.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:

java.io.IOException - in case of an I/O problem