uk.ac.starlink.util

## Class IOUtils

- java.lang.Object
- - uk.ac.starlink.util.IOUtils

-     public class IOUtils
      extends java.lang.Object

  Provides static methods which do miscellaneous input/output tasks.

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `copy(java.io.InputStream in, java.io.OutputStream out)` Copies all the bytes from a given input stream to a given output stream.
    `static byte[]` | `getLineSeparatorBytes()` Returns the platform's line separator as a byte array given the platform's default encoding.
    `static java.lang.String` | `getResourceContents(java.lang.Class<?> clazz, java.lang.String name, java.util.logging.Level level)` Reads a static resource and returns the contents as a string.
    `static void` | `println(java.io.OutputStream out, java.lang.String line)` Writes a string to an output stream followed by a new line.
    `static byte[]` | `readBytes(java.io.InputStream in, int maxLeng)` Reads a number of bytes from a stream.
    `static java.lang.String` | `readUrl(java.lang.String url)` Reads the contents of a URL as a string.
    `static void` | `skip(java.io.InputStream strm, long nskip)` Skips over a number of bytes in an `InputStream` This is implemented using `InputStream.skip(long)` but differs from it in that it guarantees to skip the bytes as specified, or to throw an exception.
    `static void` | `skipBytes(java.io.DataInput strm, long nskip)` Skips over a number of bytes in a `DataInput`.

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

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

- - ### Method Detail

    - #### skipBytes

          public static void skipBytes(java.io.DataInput strm,
                                       long nskip)
                                throws java.io.IOException

      Skips over a number of bytes in a `DataInput`. This is implemented using `DataInput.skipBytes(int)` but differs from it in that it guarantees to skip the bytes as specified, or to throw an exception.
      Parameters:
        `strm` - the stream to skip through
        `nskip` - the number of bytes to skip
      Throws:
        `java.io.EOFException` - if the end of file is reached
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalArgumentException` - if `nskip<0`

    - #### skip

          public static void skip(java.io.InputStream strm,
                                  long nskip)
                           throws java.io.IOException

      Skips over a number of bytes in an `InputStream` This is implemented using `InputStream.skip(long)` but differs from it in that it guarantees to skip the bytes as specified, or to throw an exception.
      Parameters:
        `strm` - the stream to skip through
        `nskip` - the number of bytes to skip
      Throws:
        `java.io.EOFException` - if the end of file is reached
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalArgumentException` - if `nskip<0`

    - #### getResourceContents

          public static java.lang.String getResourceContents(java.lang.Class<?> clazz,
                                                             java.lang.String name,
                                                             java.util.logging.Level level)

      Reads a static resource and returns the contents as a string. The resource is read using `clazz.getResourceAsStream(name)` and is assumed to have UTF-8 content. The result is cached so that subsequent calls will return the same value. If it can't be read, "?" is returned, and a message is written through the logging system at the requested level. This is intended for short files such as version strings.
      Parameters:
        `clazz` - class defining relative location of resource
        `name` - resource name relative to `clazz`
        `level` - logging level for failure; if null a default value is used (currently WARNING)
      Returns:
        resource content string
      See Also:
        `Class.getResourceAsStream(java.lang.String)`

    - #### readUrl

          public static java.lang.String readUrl(java.lang.String url)
                                          throws java.io.IOException

      Reads the contents of a URL as a string. The resource is assumed to have UTF-8 content. This is intended for short text resources.
      Parameters:
        `url` - string representation of URL
      Returns:
        string content of resource
      Throws:
        `java.io.IOException` - in case of read failure

    - #### println

          public static void println(java.io.OutputStream out,
                                     java.lang.String line)
                              throws java.io.IOException

      Writes a string to an output stream followed by a new line. Unlike `PrintStream.println()`, an IOException may be thrown.
      Parameters:
        `out` - destination stream
        `line` - line to write
      Throws:
        `java.io.IOException`

    - #### getLineSeparatorBytes

          public static byte[] getLineSeparatorBytes()

      Returns the platform's line separator as a byte array given the platform's default encoding. May or may not be equal to {'\n'}.
      Returns:
        line separator byte sequence

    - #### copy

          public static void copy(java.io.InputStream in,
                                  java.io.OutputStream out)
                           throws java.io.IOException

      Copies all the bytes from a given input stream to a given output stream. Neither stream is closed following the copy.
      Parameters:
        `in` - source
        `out` - destination
      Throws:
        `java.io.IOException`

    - #### readBytes

          public static byte[] readBytes(java.io.InputStream in,
                                         int maxLeng)
                                  throws java.io.IOException

      Reads a number of bytes from a stream. The specified number of bytes or the whole of the file is read, whichever is shorter.
      Parameters:
        `in` - input stream
        `maxLeng` - maximum number of bytes to read
      Returns:
        buffer of bytes containing `maxLeng` bytes read from `in`, or fewer if the stream ended early
      Throws:
        `java.io.IOException`