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)

Inner Class Summary

static class

LittleEndian.BufferUnderrunException Exception to handle buffer underruns

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

BYTE_SIZE, DOUBLE_SIZE, INT_SIZE, LONG_SIZE, SHORT_SIZE

Method Summary

static byte[]	getByteArray(byte[] data, int offset, int size) Copy a portion of a byte array
static double	getDouble(byte[] data) get a double value from the beginning of a byte array
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 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 the beginning of 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) get a short array from a byte array.
static short[]	getSimpleShortArray(byte[] data, int offset, int size) get a short array from a byte array.
static int	getUnsignedByte(byte[] data) get the unsigned value of a byte.
static int	getUnsignedByte(byte[] data, int offset) get the unsigned value of a byte.
static int	getUShort(byte[] data, int offset) Retrieves and unsigned short.
static void	putDouble(byte[] data, double value) put a double value into beginning of a byte array
static void	putDouble(byte[] data, int offset, double value) put a double value into a byte array
static void	putInt(byte[] data, int value) put an int value into beginning of a byte array
static void	putInt(byte[] data, int offset, int value) put an int value into a byte array
static void	putLong(byte[] data, int offset, long value) put a long value into a byte array
static void	putLong(byte[] data, long value) put a long value into beginning of a byte array
static void	putShort(byte[] data, int offset, short value) put a short value into a byte array
static void	putShort(byte[] data, short value) put a short value into beginning of a byte array
static void	putShortArray(byte[] data, int offset, short[] value) put a array of shorts into a byte array
static void	putUShort(byte[] data, int offset, int value) put an unsigned short value into a byte array
static byte[]	readFromStream(java.io.InputStream stream, int size) Read the appropriate number of bytes from the stream and return them to the caller.
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 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

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

getSimpleShortArray

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

get a short array from a byte array.

getShortArray

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

get a short array from a byte array. The short array is assumed to start with a word describing the length of the array.

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

getLong

public static long getLong(byte[] data)

get a long value from the beginning of a byte array

Parameters:

data - the byte array

Returns:

the long (64-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

getDouble

public static double getDouble(byte[] data)

get a double value from the beginning of a byte array

Parameters:

data - the byte array

Returns:

the double (64-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

putShortArray

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

put a array of shorts into a byte array

Parameters:

data - the byte array

offset - a starting offset into the byte array

value - the short array

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

putShort

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

put a short value into beginning of a byte array

Parameters:

data - the byte array

value - the short (16-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

putInt

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

put an int value into beginning of a byte array

Parameters:

data - the byte array

value - the int (32-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

putLong

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

put a long value into beginning of a byte array

Parameters:

data - the byte array

value - the long (64-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

putDouble

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

put a double value into beginning of a byte array

Parameters:

data - the byte array

value - the double (64-bit) value

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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

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

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

readFromStream

public static byte[] readFromStream(java.io.InputStream stream,
                                    int size)
                             throws java.io.IOException,
                                    LittleEndian.BufferUnderrunException

Read the appropriate number of bytes from the stream and return them to the caller.

It should be noted that, in an attempt to improve system performance and to prevent a transient explosion of discarded byte arrays to be garbage collected, static byte arrays are employed for the standard cases of reading a short, an int, or a long.

THIS INTRODUCES A RISK FOR THREADED OPERATIONS!

However, for the purposes of the POI project, this risk is deemed negligible. It is, however, so noted.

Parameters:

stream - the InputStream we're reading from

size - the number of bytes to read; in 99.99% of cases, this will be SHORT_SIZE, INT_SIZE, or LONG_SIZE -- but it doesn't have to be.

Returns:

the byte array containing the required number of bytes. The array will contain all zero's on end of stream

Throws:

java.io.IOException - will be propagated back to the caller

LittleEndian.BufferUnderrunException - if the stream cannot provide enough bytes

ubyteToInt

public static int ubyteToInt(byte b)

Convert an 'unsigned' byte to an integer. ie, don't carry across the sign.

getUnsignedByte

public static int getUnsignedByte(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 32 bit integer

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

getUnsignedByte

public static int getUnsignedByte(byte[] data)

get the unsigned value of a byte.

Parameters:

data - the byte array

Returns:

the unsigned value of the byte as a 32 bit integer

Throws:

java.lang.ArrayIndexOutOfBoundsException - may be thrown

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.

Throws:

java.lang.IndexOutOfBoundsException - - if copying would cause access of data outside array bounds.

getUShort

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

Retrieves and unsigned short. This is converted UP to a int so it can fit.

Parameters:

data - The data to read

offset - The offset to read the short from

Returns:

An integer representation of the short.