org.crosswire.jsword.book.sword

## Class SwordUtil

- java.lang.Object
- - org.crosswire.jsword.book.sword.SwordUtil

-     public final class SwordUtil
      extends Object

  Various utilities used by different Sword classes.
  Author:
    Joe Walker
  See Also:
    `The GNU Lesser General Public License for details.`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private static org.slf4j.Logger` | `log` The log stream

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `private` | `SwordUtil()` Prevent instantiation

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `private static void` | `clean1252(String key, byte[] data, int offset, int length)` Remove rogue characters in the source.
    `static String` | `decode(String key, byte[] data, int offset, int length, String charset)` Transform a portion of a byte array starting at an offset into a string given the encoding.
    `static String` | `decode(String key, byte[] data, int length, String charset)` Transform a portion of a byte array into a string given the encoding.
    `static String` | `decode(String key, byte[] data, String charset)` Transform a byte array into a string given the encoding.
    `protected static int` | `decodeLittleEndian16(byte[] data, int offset)` Decode little endian data from a byte array
    `static int` | `decodeLittleEndian32(byte[] data, int offset)` Decode little endian data from a byte array.
    `protected static void` | `encodeLittleEndian16(int val, byte[] data, int offset)` Encode a 16-bit little endian from an integer.
    `protected static void` | `encodeLittleEndian32(int val, byte[] data, int offset)` Encode little endian data from a byte array.
    `protected static int` | `findByte(byte[] data, byte sought)` Find a byte of data in an array
    `protected static int` | `findByte(byte[] data, int offset, byte sought)` Find a byte of data in an array
    `static URI` | `getExpandedDataPath(BookMetaData bookMetaData)` Returns where the book should be located
    `protected static byte[]` | `readNextRAF(RandomAccessFile raf, int theSize)` Read a RandomAccessFile from the current location in the file.
    `protected static byte[]` | `readRAF(RandomAccessFile raf, long offset, int theSize)` Read a RandomAccessFile
    `protected static byte[]` | `readUntilRAF(RandomAccessFile raf, byte stopByte)` Read a RandomAccessFile until a particular byte is seen
    `protected static byte[]` | `readUntilRAF(RandomAccessFile raf, int offset, byte stopByte)` Read a RandomAccessFile until a particular byte is seen
    `protected static void` | `writeNextRAF(RandomAccessFile raf, byte[] data)`
    `protected static void` | `writeRAF(RandomAccessFile raf, long offset, byte[] data)` Writes "data" to a RandomAccessFile at the "offset" position

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

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

- - ### Field Detail

    - #### log

          private static final org.slf4j.Logger log

      The log stream

  - ### Constructor Detail

    - #### SwordUtil

          private SwordUtil()

      Prevent instantiation

  - ### Method Detail

    - #### readRAF

          protected static byte[] readRAF(RandomAccessFile raf,
                       long offset,
                       int theSize)
                                   throws IOException

      Read a RandomAccessFile
      Parameters:
        `raf` - The file to read
        `offset` - The start of the record to read
        `theSize` - The number of bytes to read
      Returns:
        the read data
      Throws:
        `IOException` - on error

    - #### readNextRAF

          protected static byte[] readNextRAF(RandomAccessFile raf,
                           int theSize)
                                       throws IOException

      Read a RandomAccessFile from the current location in the file.
      Parameters:
        `raf` - The file to read
        `theSize` - The number of bytes to read
      Returns:
        the read data
      Throws:
        `IOException` - on error

    - #### writeRAF

          protected static void writeRAF(RandomAccessFile raf,
                      long offset,
                      byte[] data)
                                  throws IOException

      Writes "data" to a RandomAccessFile at the "offset" position
      Parameters:
        `raf` - RandomAccessFile
        `offset` - offset to write at
        `data` - data to write
      Throws:
        `IOException` - on error

    - #### writeNextRAF

          protected static void writeNextRAF(RandomAccessFile raf,
                          byte[] data)
                                      throws IOException

      Throws:
        `IOException`

    - #### readUntilRAF

          protected static byte[] readUntilRAF(RandomAccessFile raf,
                            int offset,
                            byte stopByte)
                                        throws IOException

      Read a RandomAccessFile until a particular byte is seen
      Parameters:
        `raf` - The file to read
        `offset` - The start of the record to read
        `stopByte` - The point at which to stop reading
      Returns:
        the read data
      Throws:
        `IOException` - on error

    - #### readUntilRAF

          protected static byte[] readUntilRAF(RandomAccessFile raf,
                            byte stopByte)
                                        throws IOException

      Read a RandomAccessFile until a particular byte is seen
      Parameters:
        `raf` - The file to read
        `stopByte` - The point at which to stop reading
      Returns:
        the read data
      Throws:
        `IOException` - on error

    - #### decodeLittleEndian32

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

      Decode little endian data from a byte array. This assumes that the high order bit is not set as this is used solely for an offset in a file in bytes. For a practical limit, 2**31 is way bigger than any document that we can have.
      Parameters:
        `data` - the byte[] from which to read 4 bytes
        `offset` - the offset into the array
      Returns:
        The decoded data

    - #### encodeLittleEndian32

          protected static void encodeLittleEndian32(int val,
                                  byte[] data,
                                  int offset)

      Encode little endian data from a byte array. This assumes that the number fits in a Java integer. That is, the range of an unsigned C integer is greater than a signed Java integer. For a practical limit, 2**31 is way bigger than any document that we can have. If this ever doesn't work, use a long for the number.
      Parameters:
        `val` - the number to encode into little endian
        `data` - the byte[] from which to write 4 bytes
        `offset` - the offset into the array

    - #### decodeLittleEndian16

          protected static int decodeLittleEndian16(byte[] data,
                                 int offset)

      Decode little endian data from a byte array
      Parameters:
        `data` - the byte[] from which to read 2 bytes
        `offset` - the offset into the array
      Returns:
        The decoded data

    - #### encodeLittleEndian16

          protected static void encodeLittleEndian16(int val,
                                  byte[] data,
                                  int offset)

      Encode a 16-bit little endian from an integer. It is assumed that the integer's lower 16 bits are the only that are set.
      Parameters:
        `data` - the byte[] from which to write 2 bytes
        `offset` - the offset into the array

    - #### findByte

          protected static int findByte(byte[] data,
                     byte sought)

      Find a byte of data in an array
      Parameters:
        `data` - The array to search
        `sought` - The data to search for
      Returns:
        The index of the found position or -1 if not found

    - #### findByte

          protected static int findByte(byte[] data,
                     int offset,
                     byte sought)

      Find a byte of data in an array
      Parameters:
        `data` - The array to search
        `offset` - The position in the array to begin looking
        `sought` - The data to search for
      Returns:
        The index of the found position or -1 if not found

    - #### decode

          public static String decode(String key,
                      byte[] data,
                      String charset)

      Transform a byte array into a string given the encoding. If the encoding is bad then it just does it as a string. Note: this may modify data. Don't use it to examine data.
      Parameters:
        `key` - the key
        `data` - The byte array to be converted
        `charset` - The encoding of the byte array
      Returns:
        a string that is UTF-8 internally

    - #### decode

          public static String decode(String key,
                      byte[] data,
                      int length,
                      String charset)

      Transform a portion of a byte array into a string given the encoding. If the encoding is bad then it just does it as a string. Note: this may modify data. Don't use it to examine data.
      Parameters:
        `key` - the key
        `data` - The byte array to be converted
        `length` - The number of bytes to use.
        `charset` - The encoding of the byte array
      Returns:
        a string that is UTF-8 internally

    - #### decode

          public static String decode(String key,
                      byte[] data,
                      int offset,
                      int length,
                      String charset)

      Transform a portion of a byte array starting at an offset into a string given the encoding. If the encoding is bad then it just does it as a string. Note: this may modify data. Don't use it to examine data.
      Parameters:
        `key` - the key
        `data` - The byte array to be converted
        `offset` - The starting position in the byte array
        `length` - The number of bytes to use.
        `charset` - The encoding of the byte array
      Returns:
        a string that is UTF-8 internally

    - #### clean1252

          private static void clean1252(String key,
                       byte[] data,
                       int offset,
                       int length)

      Remove rogue characters in the source. These are characters that are not valid in cp1252 aka WINDOWS-1252 and in UTF-8 or are non-printing control characters in the range of 0-32.

    - #### getExpandedDataPath

          public static URI getExpandedDataPath(BookMetaData bookMetaData)
                                         throws BookException

      Returns where the book should be located
      Parameters:
        `bookMetaData` - meta information about the book
      Returns:
        the URI locating the resource
      Throws:
        `BookException` - thrown if an issue is encountered, e.g. missing data files.