Files
Date: 2016-05-24

com.google.common.io

## Class Files

- java.lang.Object
- - com.google.common.io.Files

-     @Beta
      public final class Files
      extends java.lang.Object

  Provides utility methods for working with files.

  All method parameters must be non-null unless documented otherwise.

  Since:
    1.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `append(java.lang.CharSequence from, java.io.File to, java.nio.charset.Charset charset)` Appends a character sequence (such as a string) to a file using the given character set.
    `static ByteSink` | `asByteSink(java.io.File file, FileWriteMode... modes)` Returns a new `ByteSink` for writing bytes to the given file.
    `static ByteSource` | `asByteSource(java.io.File file)` Returns a new `ByteSource` for reading bytes from the given file.
    `static CharSink` | `asCharSink(java.io.File file, java.nio.charset.Charset charset, FileWriteMode... modes)` Returns a new `CharSink` for writing character data to the given file using the given character set.
    `static CharSource` | `asCharSource(java.io.File file, java.nio.charset.Charset charset)` Returns a new `CharSource` for reading character data from the given file using the given character set.
    `static void` | `copy(java.io.File from, java.nio.charset.Charset charset, java.lang.Appendable to)` Copies all characters from a file to an appendable object, using the given character set.
    `static void` | `copy(java.io.File from, java.io.File to)` Copies all the bytes from one file to another.
    `static void` | `copy(java.io.File from, java.io.OutputStream to)` Copies all bytes from a file to an output stream.
    `static void` | `createParentDirs(java.io.File file)` Creates any necessary but nonexistent parent directories of the specified file.
    `static java.io.File` | `createTempDir()` Atomically creates a new directory somewhere beneath the system's temporary directory (as defined by the `java.io.tmpdir` system property), and returns its name.
    `static boolean` | `equal(java.io.File file1, java.io.File file2)` Returns true if the files contains the same bytes.
    `static TreeTraverser<java.io.File>` | `fileTreeTraverser()` Returns a `TreeTraverser` instance for `File` trees.
    `static java.lang.String` | `getFileExtension(java.lang.String fullName)` Returns the file extension for the given file name, or the empty string if the file has no extension.
    `static java.lang.String` | `getNameWithoutExtension(java.lang.String file)` Returns the file name without its file extension or path.
    `static HashCode` | `hash(java.io.File file, HashFunction hashFunction)` Computes the hash code of the `file` using `hashFunction`.
    `static Predicate<java.io.File>` | `isDirectory()` Returns a predicate that returns the result of `File.isDirectory()` on input files.
    `static Predicate<java.io.File>` | `isFile()` Returns a predicate that returns the result of `File.isFile()` on input files.
    `static java.nio.MappedByteBuffer` | `map(java.io.File file)` Fully maps a file read-only in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)`.
    `static java.nio.MappedByteBuffer` | `map(java.io.File file, java.nio.channels.FileChannel.MapMode mode)` Fully maps a file in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)` using the requested `FileChannel.MapMode`.
    `static java.nio.MappedByteBuffer` | `map(java.io.File file, java.nio.channels.FileChannel.MapMode mode, long size)` Maps a file in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)` using the requested `FileChannel.MapMode`.
    `static void` | `move(java.io.File from, java.io.File to)` Moves a file from one path to another.
    `static java.io.BufferedReader` | `newReader(java.io.File file, java.nio.charset.Charset charset)` Returns a buffered reader that reads from a file using the given character set.
    `static java.io.BufferedWriter` | `newWriter(java.io.File file, java.nio.charset.Charset charset)` Returns a buffered writer that writes to a file using the given character set.
    `static <T> T` | `readBytes(java.io.File file, ByteProcessor<T> processor)` Process the bytes of a file.
    `static java.lang.String` | `readFirstLine(java.io.File file, java.nio.charset.Charset charset)` Reads the first line from a file.
    `static java.util.List<java.lang.String>` | `readLines(java.io.File file, java.nio.charset.Charset charset)` Reads all of the lines from a file.
    `static <T> T` | `readLines(java.io.File file, java.nio.charset.Charset charset, LineProcessor<T> callback)` Streams lines from a `File`, stopping when our callback returns false, or we have read all of the lines.
    `static java.lang.String` | `simplifyPath(java.lang.String pathname)` Returns the lexically cleaned form of the path name, usually (but not always) equivalent to the original.
    `static byte[]` | `toByteArray(java.io.File file)` Reads all bytes from a file into a byte array.
    `static java.lang.String` | `toString(java.io.File file, java.nio.charset.Charset charset)` Reads all characters from a file into a `String`, using the given character set.
    `static void` | `touch(java.io.File file)` Creates an empty file or updates the last updated timestamp on the same as the unix command of the same name.
    `static void` | `write(byte[] from, java.io.File to)` Overwrites a file with the contents of a byte array.
    `static void` | `write(java.lang.CharSequence from, java.io.File to, java.nio.charset.Charset charset)` Writes a character sequence (such as a string) to a file using the given character set.

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

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

- - ### Method Detail

    - #### newReader

          public static java.io.BufferedReader newReader(java.io.File file,
                                         java.nio.charset.Charset charset)
                                                  throws java.io.FileNotFoundException

      Returns a buffered reader that reads from a file using the given character set.
      Parameters:
        `file` - the file to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        the buffered reader
      Throws:
        `java.io.FileNotFoundException`

    - #### newWriter

          public static java.io.BufferedWriter newWriter(java.io.File file,
                                         java.nio.charset.Charset charset)
                                                  throws java.io.FileNotFoundException

      Returns a buffered writer that writes to a file using the given character set.
      Parameters:
        `file` - the file to write to
        `charset` - the charset used to encode the output stream; see `Charsets` for helpful predefined constants
      Returns:
        the buffered writer
      Throws:
        `java.io.FileNotFoundException`

    - #### asByteSource

          public static ByteSource asByteSource(java.io.File file)

      Returns a new `ByteSource` for reading bytes from the given file.
      Since:
        14.0

    - #### asByteSink

          public static ByteSink asByteSink(java.io.File file,
                            FileWriteMode... modes)

      Returns a new `ByteSink` for writing bytes to the given file. The given `modes` control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When the `APPEND` mode is provided, writes will append to the end of the file without truncating it.
      Since:
        14.0

    - #### asCharSource

          public static CharSource asCharSource(java.io.File file,
                                java.nio.charset.Charset charset)

      Returns a new `CharSource` for reading character data from the given file using the given character set.
      Since:
        14.0

    - #### asCharSink

          public static CharSink asCharSink(java.io.File file,
                            java.nio.charset.Charset charset,
                            FileWriteMode... modes)

      Returns a new `CharSink` for writing character data to the given file using the given character set. The given `modes` control how the file is opened for writing. When no mode is provided, the file will be truncated before writing. When the `APPEND` mode is provided, writes will append to the end of the file without truncating it.
      Since:
        14.0

    - #### toByteArray

          public static byte[] toByteArray(java.io.File file)
                                    throws java.io.IOException

      Reads all bytes from a file into a byte array.
      Parameters:
        `file` - the file to read from
      Returns:
        a byte array containing all the bytes from file
      Throws:
        `java.lang.IllegalArgumentException` - if the file is bigger than the largest possible byte array (2^31 - 1)
        `java.io.IOException` - if an I/O error occurs

    - #### toString

          public static java.lang.String toString(java.io.File file,
                                  java.nio.charset.Charset charset)
                                           throws java.io.IOException

      Reads all characters from a file into a `String`, using the given character set.
      Parameters:
        `file` - the file to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        a string containing all the characters from the file
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### write

          public static void write(byte[] from,
                   java.io.File to)
                            throws java.io.IOException

      Overwrites a file with the contents of a byte array.
      Parameters:
        `from` - the bytes to write
        `to` - the destination file
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### copy

          public static void copy(java.io.File from,
                  java.io.OutputStream to)
                           throws java.io.IOException

      Copies all bytes from a file to an output stream.
      Parameters:
        `from` - the source file
        `to` - the output stream
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### copy

          public static void copy(java.io.File from,
                  java.io.File to)
                           throws java.io.IOException

      Copies all the bytes from one file to another.

      Warning: If `to` represents an existing file, that file will be overwritten with the contents of `from`. If `to` and `from` refer to the same file, the contents of that file will be deleted.

      Parameters:
        `from` - the source file
        `to` - the destination file
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalArgumentException` - if `from.equals(to)`

    - #### write

          public static void write(java.lang.CharSequence from,
                   java.io.File to,
                   java.nio.charset.Charset charset)
                            throws java.io.IOException

      Writes a character sequence (such as a string) to a file using the given character set.
      Parameters:
        `from` - the character sequence to write
        `to` - the destination file
        `charset` - the charset used to encode the output stream; see `Charsets` for helpful predefined constants
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### append

          public static void append(java.lang.CharSequence from,
                    java.io.File to,
                    java.nio.charset.Charset charset)
                             throws java.io.IOException

      Appends a character sequence (such as a string) to a file using the given character set.
      Parameters:
        `from` - the character sequence to append
        `to` - the destination file
        `charset` - the charset used to encode the output stream; see `Charsets` for helpful predefined constants
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### copy

          public static void copy(java.io.File from,
                  java.nio.charset.Charset charset,
                  java.lang.Appendable to)
                           throws java.io.IOException

      Copies all characters from a file to an appendable object, using the given character set.
      Parameters:
        `from` - the source file
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
        `to` - the appendable object
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### equal

          public static boolean equal(java.io.File file1,
                      java.io.File file2)
                               throws java.io.IOException

      Returns true if the files contains the same bytes.
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### createTempDir

          public static java.io.File createTempDir()

      Atomically creates a new directory somewhere beneath the system's temporary directory (as defined by the `java.io.tmpdir` system property), and returns its name.

      Use this method instead of `File.createTempFile(String, String)` when you wish to create a directory, not a regular file. A common pitfall is to call `createTempFile`, delete the file and create a directory in its place, but this leads a race condition which can be exploited to create security vulnerabilities, especially when executable files are to be written into the directory.

      This method assumes that the temporary volume is writable, has free inodes and free blocks, and that it will not be called thousands of times per second.

      Returns:
        the newly-created directory
      Throws:
        `java.lang.IllegalStateException` - if the directory could not be created

    - #### touch

          public static void touch(java.io.File file)
                            throws java.io.IOException

      Creates an empty file or updates the last updated timestamp on the same as the unix command of the same name.
      Parameters:
        `file` - the file to create or update
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### createParentDirs

          public static void createParentDirs(java.io.File file)
                                       throws java.io.IOException

      Creates any necessary but nonexistent parent directories of the specified file. Note that if this operation fails it may have succeeded in creating some (but not all) of the necessary parent directories.
      Throws:
        `java.io.IOException` - if an I/O error occurs, or if any necessary but nonexistent parent directories of the specified file could not be created.
      Since:
        4.0

    - #### move

          public static void move(java.io.File from,
                  java.io.File to)
                           throws java.io.IOException

      Moves a file from one path to another. This method can rename a file and/or move it to a different directory. In either case `to` must be the target path for the file itself; not just the new name for the file or the path to the new parent directory.
      Parameters:
        `from` - the source file
        `to` - the destination file
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `java.lang.IllegalArgumentException` - if `from.equals(to)`

    - #### readFirstLine

          public static java.lang.String readFirstLine(java.io.File file,
                                       java.nio.charset.Charset charset)
                                                throws java.io.IOException

      Reads the first line from a file. The line does not include line-termination characters, but does include other leading and trailing whitespace.
      Parameters:
        `file` - the file to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        the first line, or null if the file is empty
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readLines

          public static java.util.List<java.lang.String> readLines(java.io.File file,
                                                   java.nio.charset.Charset charset)
                                                            throws java.io.IOException

      Reads all of the lines from a file. The lines do not include line-termination characters, but do include other leading and trailing whitespace.

      This method returns a mutable `List`. For an `ImmutableList`, use `Files.asCharSource(file, charset).readLines()`.

      Parameters:
        `file` - the file to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
      Returns:
        a mutable `List` containing all the lines
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readLines

          public static <T> T readLines(java.io.File file,
                        java.nio.charset.Charset charset,
                        LineProcessor<T> callback)
                             throws java.io.IOException

      Streams lines from a `File`, stopping when our callback returns false, or we have read all of the lines.
      Parameters:
        `file` - the file to read from
        `charset` - the charset used to decode the input stream; see `Charsets` for helpful predefined constants
        `callback` - the `LineProcessor` to use to handle the lines
      Returns:
        the output of processing the lines
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### readBytes

          public static <T> T readBytes(java.io.File file,
                        ByteProcessor<T> processor)
                             throws java.io.IOException

      Process the bytes of a file.

      (If this seems too complicated, maybe you're looking for `toByteArray(java.io.File)`.)

      Parameters:
        `file` - the file to read
        `processor` - the object to which the bytes of the file are passed.
      Returns:
        the result of the byte processor
      Throws:
        `java.io.IOException` - if an I/O error occurs

    - #### hash

          public static HashCode hash(java.io.File file,
                      HashFunction hashFunction)
                               throws java.io.IOException

      Computes the hash code of the `file` using `hashFunction`.
      Parameters:
        `file` - the file to read
        `hashFunction` - the hash function to use to hash the data
      Returns:
        the `HashCode` of all of the bytes in the file
      Throws:
        `java.io.IOException` - if an I/O error occurs
      Since:
        12.0

    - #### map

          public static java.nio.MappedByteBuffer map(java.io.File file)
                                               throws java.io.IOException

      Fully maps a file read-only in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)`.

      Files are mapped from offset 0 to its length.

      This only works for files <= `Integer.MAX_VALUE` bytes.

      Parameters:
        `file` - the file to map
      Returns:
        a read-only buffer reflecting `file`
      Throws:
        `java.io.FileNotFoundException` - if the `file` does not exist
        `java.io.IOException` - if an I/O error occurs
      Since:
        2.0
      See Also:
        `FileChannel.map(MapMode, long, long)`

    - #### map

          public static java.nio.MappedByteBuffer map(java.io.File file,
                                      java.nio.channels.FileChannel.MapMode mode)
                                               throws java.io.IOException

      Fully maps a file in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)` using the requested `FileChannel.MapMode`.

      Files are mapped from offset 0 to its length.

      This only works for files <= `Integer.MAX_VALUE` bytes.

      Parameters:
        `file` - the file to map
        `mode` - the mode to use when mapping `file`
      Returns:
        a buffer reflecting `file`
      Throws:
        `java.io.FileNotFoundException` - if the `file` does not exist
        `java.io.IOException` - if an I/O error occurs
      Since:
        2.0
      See Also:
        `FileChannel.map(MapMode, long, long)`

    - #### map

          public static java.nio.MappedByteBuffer map(java.io.File file,
                                      java.nio.channels.FileChannel.MapMode mode,
                                      long size)
                                               throws java.io.FileNotFoundException,
                                                      java.io.IOException

      Maps a file in to memory as per `FileChannel.map(java.nio.channels.FileChannel.MapMode, long, long)` using the requested `FileChannel.MapMode`.

      Files are mapped from offset 0 to `size`.

      If the mode is `FileChannel.MapMode.READ_WRITE` and the file does not exist, it will be created with the requested `size`. Thus this method is useful for creating memory mapped files which do not yet exist.

      This only works for files <= `Integer.MAX_VALUE` bytes.

      Parameters:
        `file` - the file to map
        `mode` - the mode to use when mapping `file`
      Returns:
        a buffer reflecting `file`
      Throws:
        `java.io.IOException` - if an I/O error occurs
        `java.io.FileNotFoundException`
      Since:
        2.0
      See Also:
        `FileChannel.map(MapMode, long, long)`

    - #### simplifyPath

          public static java.lang.String simplifyPath(java.lang.String pathname)

      Returns the lexically cleaned form of the path name, usually (but not always) equivalent to the original. The following heuristics are used:
      - empty string becomes .
      - . stays as .
      - fold out ./
      - fold out ../ when possible
      - collapse multiple slashes
      - delete trailing slashes (unless the path is just "/")

      These heuristics do not always match the behavior of the filesystem. In particular, consider the path `a/../b`, which `simplifyPath` will change to `b`. If `a` is a symlink to `x`, `a/../b` may refer to a sibling of `x`, rather than the sibling of `a` referred to by `b`.

      Since:
        11.0

    - #### getFileExtension

          public static java.lang.String getFileExtension(java.lang.String fullName)

      Returns the file extension for the given file name, or the empty string if the file has no extension. The result does not include the '`.`'.
      Since:
        11.0

    - #### getNameWithoutExtension

          public static java.lang.String getNameWithoutExtension(java.lang.String file)

      Returns the file name without its file extension or path. This is similar to the `basename` unix command. The result does not include the '`.`'.
      Parameters:
        `file` - The name of the file to trim the extension from. This can be either a fully qualified file name (including a path) or just a file name.
      Returns:
        The file name without its path or extension.
      Since:
        14.0

    - #### fileTreeTraverser

          public static TreeTraverser<java.io.File> fileTreeTraverser()

      Returns a `TreeTraverser` instance for `File` trees.

      Warning: `File` provides no support for symbolic links, and as such there is no way to ensure that a symbolic link to a directory is not followed when traversing the tree. In this case, iterables created by this traverser could contain files that are outside of the given directory or even be infinite if there is a symbolic link loop.

      Since:
        15.0

    - #### isDirectory

          public static Predicate<java.io.File> isDirectory()

      Returns a predicate that returns the result of `File.isDirectory()` on input files.
      Since:
        15.0

    - #### isFile

          public static Predicate<java.io.File> isFile()

      Returns a predicate that returns the result of `File.isFile()` on input files.
      Since:
        15.0