source: josm/trunk/src/com/drew/lang/RandomAccessReader.java@ 8506

/*
 * Copyright 2002-2015 Drew Noakes
 *
 *    Licensed under the Apache License, Version 2.0 (the "License");
 *    you may not use this file except in compliance with the License.
 *    You may obtain a copy of the License at
 *
 *        http://www.apache.org/licenses/LICENSE-2.0
 *
 *    Unless required by applicable law or agreed to in writing, software
 *    distributed under the License is distributed on an "AS IS" BASIS,
 *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *    See the License for the specific language governing permissions and
 *    limitations under the License.
 *
 * More information about this project is available at:
 *
 *    https://drewnoakes.com/code/exif/
 *    https://github.com/drewnoakes/metadata-extractor
 */

package com.drew.lang;

import com.drew.lang.annotations.NotNull;

import java.io.IOException;
import java.io.UnsupportedEncodingException;

/**
 * Base class for random access data reading operations of common data types.
 * <p>
 * By default, the reader operates with Motorola byte order (big endianness).  This can be changed by calling
 * {@link com.drew.lang.RandomAccessReader#setMotorolaByteOrder(boolean)}.
 * <p>
 * Concrete implementations include:
 * <ul>
 *     <li>{@link ByteArrayReader}</li>
 *     <li>{@link RandomAccessStreamReader}</li>
 * </ul>
 *
 * @author Drew Noakes https://drewnoakes.com
 */
public abstract class RandomAccessReader
{
    private boolean _isMotorolaByteOrder = true;

    /**
     * Gets the byte value at the specified byte <code>index</code>.
     * <p>
     * Implementations should not perform any bounds checking in this method. That should be performed
     * in <code>validateIndex</code> and <code>isValidIndex</code>.
     *
     * @param index The index from which to read the byte
     * @return The read byte value
     * @throws IllegalArgumentException <code>index</code> or <code>count</code> are negative
     * @throws BufferBoundsException if the requested byte is beyond the end of the underlying data source
     * @throws IOException if the byte is unable to be read
     */
    protected abstract byte getByte(int index) throws IOException;

    /**
     * Returns the required number of bytes from the specified index from the underlying source.
     *
     * @param index The index from which the bytes begins in the underlying source
     * @param count The number of bytes to be returned
     * @return The requested bytes
     * @throws IllegalArgumentException <code>index</code> or <code>count</code> are negative
     * @throws BufferBoundsException if the requested bytes extend beyond the end of the underlying data source
     * @throws IOException if the byte is unable to be read
     */
    @NotNull
    public abstract byte[] getBytes(int index, int count) throws IOException;

    /**
     * Ensures that the buffered bytes extend to cover the specified index. If not, an attempt is made
     * to read to that point.
     * <p>
     * If the stream ends before the point is reached, a {@link BufferBoundsException} is raised.
     *
     * @param index the index from which the required bytes start
     * @param bytesRequested the number of bytes which are required
     * @throws IOException if the stream ends before the required number of bytes are acquired
     */
    protected abstract void validateIndex(int index, int bytesRequested) throws IOException;

    protected abstract boolean isValidIndex(int index, int bytesRequested) throws IOException;

    /**
     * Returns the length of the data source in bytes.
     * <p>
     * This is a simple operation for implementations (such as {@link RandomAccessFileReader} and
     * {@link ByteArrayReader}) that have the entire data source available.
     * <p>
     * Users of this method must be aware that sequentially accessed implementations such as
     * {@link RandomAccessStreamReader} will have to read and buffer the entire data source in
     * order to determine the length.
     *
     * @return the length of the data source, in bytes.
     */
    public abstract long getLength() throws IOException;

    /**
     * Sets the endianness of this reader.
     * <ul>
     * <li><code>true</code> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</li>
     * <li><code>false</code> for Intel (or little) endianness, with LSB before MSB.</li>
     * </ul>
     *
     * @param motorolaByteOrder <code>true</code> for Motorola/big endian, <code>false</code> for Intel/little endian
     */
    public void setMotorolaByteOrder(boolean motorolaByteOrder)
    {
        _isMotorolaByteOrder = motorolaByteOrder;
    }

    /**
     * Gets the endianness of this reader.
     * <ul>
     * <li><code>true</code> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</li>
     * <li><code>false</code> for Intel (or little) endianness, with LSB before MSB.</li>
     * </ul>
     */
    public boolean isMotorolaByteOrder()
    {
        return _isMotorolaByteOrder;
    }

    /**
     * Gets whether a bit at a specific index is set or not.
     *
     * @param index the number of bits at which to test
     * @return true if the bit is set, otherwise false
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public boolean getBit(int index) throws IOException
    {
        int byteIndex = index / 8;
        int bitIndex = index % 8;

        validateIndex(byteIndex, 1);

        byte b = getByte(byteIndex);
        return ((b >> bitIndex) & 1) == 1;
    }

    /**
     * Returns an unsigned 8-bit int calculated from one byte of data at the specified index.
     *
     * @param index position within the data buffer to read byte
     * @return the 8 bit int value, between 0 and 255
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public short getUInt8(int index) throws IOException
    {
        validateIndex(index, 1);

        return (short) (getByte(index) & 0xFF);
    }

    /**
     * Returns a signed 8-bit int calculated from one byte of data at the specified index.
     *
     * @param index position within the data buffer to read byte
     * @return the 8 bit int value, between 0x00 and 0xFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public byte getInt8(int index) throws IOException
    {
        validateIndex(index, 1);

        return getByte(index);
    }

    /**
     * Returns an unsigned 16-bit int calculated from two bytes of data at the specified index.
     *
     * @param index position within the data buffer to read first byte
     * @return the 16 bit int value, between 0x0000 and 0xFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public int getUInt16(int index) throws IOException
    {
        validateIndex(index, 2);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first
            return (getByte(index    ) << 8 & 0xFF00) |
                   (getByte(index + 1)      & 0xFF);
        } else {
            // Intel ordering - LSB first
            return (getByte(index + 1) << 8 & 0xFF00) |
                   (getByte(index    )      & 0xFF);
        }
    }

    /**
     * Returns a signed 16-bit int calculated from two bytes of data at the specified index (MSB, LSB).
     *
     * @param index position within the data buffer to read first byte
     * @return the 16 bit int value, between 0x0000 and 0xFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public short getInt16(int index) throws IOException
    {
        validateIndex(index, 2);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first
            return (short) (((short)getByte(index    ) << 8 & (short)0xFF00) |
                            ((short)getByte(index + 1)      & (short)0xFF));
        } else {
            // Intel ordering - LSB first
            return (short) (((short)getByte(index + 1) << 8 & (short)0xFF00) |
                            ((short)getByte(index    )      & (short)0xFF));
        }
    }

    /**
     * Get a 24-bit unsigned integer from the buffer, returning it as an int.
     *
     * @param index position within the data buffer to read first byte
     * @return the unsigned 24-bit int value as a long, between 0x00000000 and 0x00FFFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public int getInt24(int index) throws IOException
    {
        validateIndex(index, 3);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first (big endian)
            return (((int)getByte(index    )) << 16 & 0xFF0000) |
                   (((int)getByte(index + 1)) << 8  & 0xFF00) |
                   (((int)getByte(index + 2))       & 0xFF);
        } else {
            // Intel ordering - LSB first (little endian)
            return (((int)getByte(index + 2)) << 16 & 0xFF0000) |
                   (((int)getByte(index + 1)) << 8  & 0xFF00) |
                   (((int)getByte(index    ))       & 0xFF);
        }
    }

    /**
     * Get a 32-bit unsigned integer from the buffer, returning it as a long.
     *
     * @param index position within the data buffer to read first byte
     * @return the unsigned 32-bit int value as a long, between 0x00000000 and 0xFFFFFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public long getUInt32(int index) throws IOException
    {
        validateIndex(index, 4);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first (big endian)
            return (((long)getByte(index    )) << 24 & 0xFF000000L) |
                   (((long)getByte(index + 1)) << 16 & 0xFF0000L) |
                   (((long)getByte(index + 2)) << 8  & 0xFF00L) |
                   (((long)getByte(index + 3))       & 0xFFL);
        } else {
            // Intel ordering - LSB first (little endian)
            return (((long)getByte(index + 3)) << 24 & 0xFF000000L) |
                   (((long)getByte(index + 2)) << 16 & 0xFF0000L) |
                   (((long)getByte(index + 1)) << 8  & 0xFF00L) |
                   (((long)getByte(index    ))       & 0xFFL);
        }
    }

    /**
     * Returns a signed 32-bit integer from four bytes of data at the specified index the buffer.
     *
     * @param index position within the data buffer to read first byte
     * @return the signed 32 bit int value, between 0x00000000 and 0xFFFFFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public int getInt32(int index) throws IOException
    {
        validateIndex(index, 4);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first (big endian)
            return (getByte(index    ) << 24 & 0xFF000000) |
                   (getByte(index + 1) << 16 & 0xFF0000) |
                   (getByte(index + 2) << 8  & 0xFF00) |
                   (getByte(index + 3)       & 0xFF);
        } else {
            // Intel ordering - LSB first (little endian)
            return (getByte(index + 3) << 24 & 0xFF000000) |
                   (getByte(index + 2) << 16 & 0xFF0000) |
                   (getByte(index + 1) << 8  & 0xFF00) |
                   (getByte(index    )       & 0xFF);
        }
    }

    /**
     * Get a signed 64-bit integer from the buffer.
     *
     * @param index position within the data buffer to read first byte
     * @return the 64 bit int value, between 0x0000000000000000 and 0xFFFFFFFFFFFFFFFF
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public long getInt64(int index) throws IOException
    {
        validateIndex(index, 8);

        if (_isMotorolaByteOrder) {
            // Motorola - MSB first
            return ((long)getByte(index    ) << 56 & 0xFF00000000000000L) |
                   ((long)getByte(index + 1) << 48 & 0xFF000000000000L) |
                   ((long)getByte(index + 2) << 40 & 0xFF0000000000L) |
                   ((long)getByte(index + 3) << 32 & 0xFF00000000L) |
                   ((long)getByte(index + 4) << 24 & 0xFF000000L) |
                   ((long)getByte(index + 5) << 16 & 0xFF0000L) |
                   ((long)getByte(index + 6) << 8  & 0xFF00L) |
                   ((long)getByte(index + 7)       & 0xFFL);
        } else {
            // Intel ordering - LSB first
            return ((long)getByte(index + 7) << 56 & 0xFF00000000000000L) |
                   ((long)getByte(index + 6) << 48 & 0xFF000000000000L) |
                   ((long)getByte(index + 5) << 40 & 0xFF0000000000L) |
                   ((long)getByte(index + 4) << 32 & 0xFF00000000L) |
                   ((long)getByte(index + 3) << 24 & 0xFF000000L) |
                   ((long)getByte(index + 2) << 16 & 0xFF0000L) |
                   ((long)getByte(index + 1) << 8  & 0xFF00L) |
                   ((long)getByte(index    )       & 0xFFL);
        }
    }

    /**
     * Gets a s15.16 fixed point float from the buffer.
     * <p>
     * This particular fixed point encoding has one sign bit, 15 numerator bits and 16 denominator bits.
     *
     * @return the floating point value
     * @throws IOException the buffer does not contain enough bytes to service the request, or index is negative
     */
    public float getS15Fixed16(int index) throws IOException
    {
        validateIndex(index, 4);

        if (_isMotorolaByteOrder) {
            float res = (getByte(index    ) & 0xFF) << 8 |
                        (getByte(index + 1) & 0xFF);
            int d =     (getByte(index + 2) & 0xFF) << 8 |
                        (getByte(index + 3) & 0xFF);
            return (float)(res + d/65536.0);
        } else {
            // this particular branch is untested
            float res = (getByte(index + 3) & 0xFF) << 8 |
                        (getByte(index + 2) & 0xFF);
            int d =     (getByte(index + 1) & 0xFF) << 8 |
                        (getByte(index    ) & 0xFF);
            return (float)(res + d/65536.0);
        }
    }

    public float getFloat32(int index) throws IOException
    {
        return Float.intBitsToFloat(getInt32(index));
    }

    public double getDouble64(int index) throws IOException
    {
        return Double.longBitsToDouble(getInt64(index));
    }

    @NotNull
    public String getString(int index, int bytesRequested) throws IOException
    {
        return new String(getBytes(index, bytesRequested));
    }

    @NotNull
    public String getString(int index, int bytesRequested, String charset) throws IOException
    {
        byte[] bytes = getBytes(index, bytesRequested);
        try {
            return new String(bytes, charset);
        } catch (UnsupportedEncodingException e) {
            return new String(bytes);
        }
    }

    /**
     * Creates a String from the _data buffer starting at the specified index,
     * and ending where <code>byte=='\0'</code> or where <code>length==maxLength</code>.
     *
     * @param index          The index within the buffer at which to start reading the string.
     * @param maxLengthBytes The maximum number of bytes to read.  If a zero-byte is not reached within this limit,
     *                       reading will stop and the string will be truncated to this length.
     * @return The read string.
     * @throws IOException The buffer does not contain enough bytes to satisfy this request.
     */
    @NotNull
    public String getNullTerminatedString(int index, int maxLengthBytes) throws IOException
    {
        // NOTE currently only really suited to single-byte character strings

        byte[] bytes = getBytes(index, maxLengthBytes);

        // Count the number of non-null bytes
        int length = 0;
        while (length < bytes.length && bytes[length] != '\0')
            length++;

        return new String(bytes, 0, length);
    }
}