Clarify and correct EndianUtils and SwappedDataInputStream API doc (#566)
* Clarify and correct API doc
* use code tags
* Correct Javadoc for SwappedDataInputStream
diff --git a/src/main/java/org/apache/commons/io/EndianUtils.java b/src/main/java/org/apache/commons/io/EndianUtils.java
index ac3c645..7eaa9a1 100644
--- a/src/main/java/org/apache/commons/io/EndianUtils.java
+++ b/src/main/java/org/apache/commons/io/EndianUtils.java
@@ -24,14 +24,21 @@
import java.io.OutputStream;
/**
- * Helps with different endian systems.
+ * Helps with reading and writing primitive numeric types ({@code short},
+ * {@code int}, {@code long}, {@code float}, and {@code double}) that are
+ * encoded in little endian using two's complement or unsigned representations.
* <p>
- * Different computer architectures adopt different conventions for
- * byte ordering. In so-called "Little Endian" architectures (eg Intel),
+ * 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. For "Big Endian" architectures
- * (eg Motorola), the situation is reversed.
- * This class helps you solve this incompatibility.
+ * 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. {@code DataInputStream} and
+ * {@code 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.
* </p>
* <p>
* Provenance: Excalibur
@@ -56,19 +63,20 @@
}
/**
- * Reads a "double" value from a byte array at a given offset. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code double} value from a byte array at a given offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
*/
public static double readSwappedDouble(final byte[] data, final int offset) {
return Double.longBitsToDouble(readSwappedLong(data, offset));
}
/**
- * Reads a "double" value from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code double} value from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -78,19 +86,20 @@
}
/**
- * Reads a "float" value from a byte array at a given offset. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code float} value from a byte array at a given offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
*/
public static float readSwappedFloat(final byte[] data, final int offset) {
return Float.intBitsToFloat(readSwappedInteger(data, offset));
}
/**
- * Reads a "float" value from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code float} value from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -100,11 +109,12 @@
}
/**
- * Reads an "int" value from a byte array at a given offset. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code int} value from a byte array at a given offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
*/
public static int readSwappedInteger(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
@@ -115,8 +125,8 @@
}
/**
- * Reads an "int" value from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code int} value from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -130,11 +140,12 @@
}
/**
- * Reads a "long" value from a byte array at a given offset. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code long} value from a byte array at a given offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
*/
public static long readSwappedLong(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Long.SIZE / Byte.SIZE);
@@ -144,8 +155,8 @@
}
/**
- * Reads a "long" value from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code long} value from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -159,11 +170,12 @@
}
/**
- * Reads a "short" value from a byte array at a given offset. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code short} value from a byte array at a given offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
*/
public static short readSwappedShort(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -171,8 +183,8 @@
}
/**
- * Reads a "short" value from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian {@code short} value from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -182,13 +194,14 @@
}
/**
- * Reads an unsigned integer (32-bit) value from a byte array at a given
- * offset. The value is converted to the opposed endian system while
- * reading.
+ * Reads a little endian unsigned integer (32-bit) value from a byte array at a given
+ * offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
- */
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
+ */
public static long readSwappedUnsignedInteger(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
final long low = ((data[offset + 0] & 0xff) << 0) +
@@ -199,8 +212,8 @@
}
/**
- * Reads an unsigned integer (32-bit) from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads a little endian unsigned integer (32-bit) from an InputStream.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -216,12 +229,13 @@
}
/**
- * Reads an unsigned short (16-bit) value from a byte array at a given
- * offset. The value is converted to the opposed endian system while
- * reading.
+ * Reads an unsigned short (16-bit) value from a byte array in little endian order at a given
+ * offset.
+ *
* @param data source byte array
* @param offset starting offset in the byte array
* @return the value read
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
*/
public static int readSwappedUnsignedShort(final byte[] data, final int offset) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -229,8 +243,8 @@
}
/**
- * Reads an unsigned short (16-bit) from an InputStream. The value is
- * converted to the opposed endian system while reading.
+ * Reads an unsigned short (16-bit) from an InputStream in little endian order.
+ *
* @param input source InputStream
* @return the value just read
* @throws IOException in case of an I/O problem
@@ -243,7 +257,12 @@
}
/**
- * Converts a "double" value between endian systems.
+ * Converts a {@code double} value from big endian to little endian
+ * and vice versa. That is, it converts the {@code double} to bytes,
+ * reverses the bytes, and then reinterprets those bytes as a new {@code double}.
+ * This can be useful if you have a number that was read from the
+ * underlying source in the wrong endianness.
+ *
* @param value value to convert
* @return the converted value
*/
@@ -252,7 +271,8 @@
}
/**
- * Converts a "float" value between endian systems.
+ * Converts a {@code float} value from big endian to little endian and vice versa.
+ *
* @param value value to convert
* @return the converted value
*/
@@ -261,7 +281,8 @@
}
/**
- * Converts an "int" value between endian systems.
+ * Converts an {@code int} value from big endian to little endian and vice versa.
+ *
* @param value value to convert
* @return the converted value
*/
@@ -274,7 +295,8 @@
}
/**
- * Converts a "long" value between endian systems.
+ * Converts a {@code long} value from big endian to little endian and vice versa.
+ *
* @param value value to convert
* @return the converted value
*/
@@ -291,7 +313,8 @@
}
/**
- * Converts a "short" value between endian systems.
+ * Converts a {@code short} value from big endian to little endian and vice versa.
+ *
* @param value value to convert
* @return the converted value
*/
@@ -301,7 +324,8 @@
}
/**
- * Validates if the provided byte array have enough data.
+ * Validates if the provided byte array has enough data.
+ *
* @param data the input byte array
* @param offset the input offset
* @param byteNeeded the needed number of bytes
@@ -314,19 +338,20 @@
}
/**
- * Writes a "double" value to a byte array at a given offset. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 8 bytes of a {@code double} to a byte array at a given offset in little endian order.
+ *
* @param data target byte array
* @param offset starting offset in the byte array
* @param value value to write
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
*/
public static void writeSwappedDouble(final byte[] data, final int offset, final double value) {
writeSwappedLong(data, offset, Double.doubleToLongBits(value));
}
/**
- * Writes a "double" value to an OutputStream. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 8 bytes of a {@code double} to an output stream in little endian order.
+ *
* @param output target OutputStream
* @param value value to write
* @throws IOException in case of an I/O problem
@@ -336,33 +361,35 @@
}
/**
- * Writes a "float" value to a byte array at a given offset. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 4 bytes of a {@code float} to a byte array at a given offset in little endian order.
+ *
* @param data target byte array
* @param offset starting offset in the byte array
* @param value value to write
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
*/
public static void writeSwappedFloat(final byte[] data, final int offset, final float value) {
writeSwappedInteger(data, offset, Float.floatToIntBits(value));
}
/**
- * Writes a "float" value to an OutputStream. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 4 bytes of a {@code float} to an output stream in little endian order.
+ *
* @param output target OutputStream
* @param value value to write
* @throws IOException in case of an I/O problem
- */
+ */
public static void writeSwappedFloat(final OutputStream output, final float value) throws IOException {
writeSwappedInteger(output, Float.floatToIntBits(value));
}
/**
- * Writes an "int" value to a byte array at a given offset. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 4 bytes of an {@code int} to a byte array at a given offset in little endian order.
+ *
* @param data target byte array
* @param offset starting offset in the byte array
* @param value value to write
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 4 bytes
*/
public static void writeSwappedInteger(final byte[] data, final int offset, final int value) {
validateByteArrayOffset(data, offset, Integer.SIZE / Byte.SIZE);
@@ -373,7 +400,7 @@
}
/**
- * Writes an "int" value to an OutputStream. The value is converted to the opposed endian system while writing.
+ * Writes the 4 bytes of an {@code int} to an output stream in little endian order.
*
* @param output target OutputStream
* @param value value to write
@@ -387,11 +414,12 @@
}
/**
- * Writes a "long" value to a byte array at a given offset. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 8 bytes of a {@code long} to a byte array at a given offset in little endian order.
+ *
* @param data target byte array
* @param offset starting offset in the byte array
* @param value value to write
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 8 bytes
*/
public static void writeSwappedLong(final byte[] data, final int offset, final long value) {
validateByteArrayOffset(data, offset, Long.SIZE / Byte.SIZE);
@@ -406,8 +434,8 @@
}
/**
- * Writes a "long" value to an OutputStream. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 8 bytes of a {@code long} to an output stream in little endian order.
+ *
* @param output target OutputStream
* @param value value to write
* @throws IOException in case of an I/O problem
@@ -424,11 +452,12 @@
}
/**
- * Writes a "short" value to a byte array at a given offset. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 2 bytes of a {@code short} to a byte array at a given offset in little endian order.
+ *
* @param data target byte array
* @param offset starting offset in the byte array
* @param value value to write
+ * @throws IllegalArgumentException if the part of the byte array starting at offset does not have at least 2 bytes
*/
public static void writeSwappedShort(final byte[] data, final int offset, final short value) {
validateByteArrayOffset(data, offset, Short.SIZE / Byte.SIZE);
@@ -437,8 +466,8 @@
}
/**
- * Writes a "short" value to an OutputStream. The value is
- * converted to the opposed endian system while writing.
+ * Writes the 2 bytes of a {@code short} to an output stream using little endian encoding.
+ *
* @param output target OutputStream
* @param value value to write
* @throws IOException in case of an I/O problem
diff --git a/src/main/java/org/apache/commons/io/input/SwappedDataInputStream.java b/src/main/java/org/apache/commons/io/input/SwappedDataInputStream.java
index 303bfe2..e182974 100644
--- a/src/main/java/org/apache/commons/io/input/SwappedDataInputStream.java
+++ b/src/main/java/org/apache/commons/io/input/SwappedDataInputStream.java
@@ -68,9 +68,9 @@
}
/**
- * Reads a character delegating to {@link #readShort()}.
+ * Reads a 2 byte, unsigned, little endian UTF-16 code point.
*
- * @return the byte read or -1 if the end of stream
+ * @return the UTF-16 code point read or -1 if the end of stream
* @throws IOException if an I/O error occurs.
* @throws EOFException if an end of file is reached unexpectedly
*/
@@ -80,7 +80,7 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedDouble(InputStream)}.
+ * Reads an 8 byte, two's complement, little-endian long.
*
* @return the read long
* @throws IOException if an I/O error occurs.
@@ -92,9 +92,9 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedFloat(InputStream)}.
+ * Reads a 4 byte, IEEE 754, little-endian float.
*
- * @return the read long
+ * @return the read float
* @throws IOException if an I/O error occurs.
* @throws EOFException if an end of file is reached unexpectedly
*/
@@ -141,9 +141,9 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedInteger(InputStream)}.
+ * Reads a 4 byte, two's complement little-endian integer.
*
- * @return the read long
+ * @return the read int
* @throws EOFException if an end of file is reached unexpectedly
* @throws IOException if an I/O error occurs.
*/
@@ -157,7 +157,8 @@
*
* @return the line read
* @throws EOFException if an end of file is reached unexpectedly
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs
+ * @throws UnsupportedOperationException always
*/
@Override
public String readLine() throws IOException, EOFException {
@@ -165,7 +166,7 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedLong(InputStream)}.
+ * Reads an 8 byte, two's complement little-endian integer.
*
* @return the read long
* @throws EOFException if an end of file is reached unexpectedly
@@ -177,9 +178,9 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedShort(InputStream)}.
+ * Reads a 2 byte, two's complement, little-endian integer.
*
- * @return the read long
+ * @return the read short
* @throws EOFException if an end of file is reached unexpectedly
* @throws IOException if an I/O error occurs.
*/
@@ -201,9 +202,9 @@
}
/**
- * Delegates to {@link EndianUtils#readSwappedUnsignedShort(InputStream)}.
+ * Reads a 2 byte, unsigned, little-endian integer.
*
- * @return the read long
+ * @return the read short
* @throws EOFException if an end of file is reached unexpectedly
* @throws IOException if an I/O error occurs.
*/
@@ -215,9 +216,10 @@
/**
* Not currently supported - throws {@link UnsupportedOperationException}.
*
- * @return UTF String read
+ * @return never
* @throws EOFException if an end of file is reached unexpectedly
- * @throws IOException if an I/O error occurs.
+ * @throws IOException if an I/O error occurs
+ * @throws UnsupportedOperationException always
*/
@Override
public String readUTF() throws IOException, EOFException {
@@ -228,12 +230,11 @@
* Invokes the delegate's {@code skip(int)} method.
*
* @param count the number of bytes to skip
- * @return the number of bytes to skipped or -1 if the end of stream
- * @throws EOFException if an end of file is reached unexpectedly
- * @throws IOException if an I/O error occurs.
+ * @return the number of bytes skipped or -1 if the end of stream
+ * @throws IOException if an I/O error occurs
*/
@Override
- public int skipBytes(final int count) throws IOException, EOFException {
+ public int skipBytes(final int count) throws IOException {
return (int) in.skip(count);
}
