Package arc.files

Class Fi

java.lang.Object
arc.files.Fi
Direct Known Subclasses:
AndroidFi, IOSFi, SdlFiles.SdlFi, ZipFi
public class Fi extends Object
Represents a file or directory on the filesystem, classpath, Android SD card, or Android assets directory. FileHandles are created via a Files instance.

Because some of the file types are backed by composite files and may be compressed (for example, if they are in an Android .apk or are found via the classpath), the methods for extracting a path() or file() may not be appropriate for all types. Use the Reader or Stream methods here to hide these dependencies from your platform independent code.

  • Field Details

  • Constructor Details

    • Fi

      protected Fi()

    • Fi

      public Fi(String fileName)
      Creates a new absolute FileHandle for the file name. Use this for tools on the desktop that don't need any of the backends. Do not use this constructor in case you write something cross-platform. Use the Files interface instead.
      Parameters:
      fileName - the filename.

    • Fi

      public Fi(File file)
      Creates a new absolute FileHandle for the File. Use this for tools on the desktop that don't need any of the backends. Do not use this constructor in case you write something cross-platform. Use the Files interface instead.
      Parameters:
      file - the file.

    • Fi

      public Fi(String fileName, Files.FileType type)

    • Fi

      protected Fi(File file, Files.FileType type)

  • Method Details

    • get

      public static Fi get(String path)

    • tempFile

      public static Fi tempFile(String prefix)

    • tempDirectory

      public static Fi tempDirectory(String prefix)

    • path

      public String path()
      Returns:
      the path of the file as specified on construction. Backward slashes will be replaced by forward slashes.

    • absolutePath

      public String absolutePath()
      Returns:
      the absolute path to this file without backslashes.

    • name

      public String name()
      Returns:
      the name of the file, without any parent paths.

    • extEquals

      public boolean extEquals(String ext)
      Returns:
      whether this file's extension is equal to the specified string.

    • extension

      public String extension()
      Returns the file extension (without the dot) or an empty string if the file name doesn't contain a dot.

    • nameWithoutExtension

      public String nameWithoutExtension()
      Returns:
      the name of the file, without parent paths or the extension.

    • pathWithoutExtension

      public String pathWithoutExtension()
      Returns:
      the path and filename without the extension, e.g. dir/dir2/file.png -> dir/dir2/file. backward slashes will be returned as forward slashes.

    • type

      public Files.FileType type()

    • file

      public File file()
      Returns a java.io.File that represents this file handle. Note the returned file will only be usable for Files.absolute(java.lang.String) and Files.external(java.lang.String) file handles.

    • read

      public InputStream read()
      Returns a stream for reading this file as bytes.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • read

      public BufferedInputStream read(int bufferSize)
      Returns a buffered stream for reading this file as bytes.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • reader

      public Reader reader()
      Returns a reader for reading this file as characters.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • reader

      public Reader reader(String charset)
      Returns a reader for reading this file as characters.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • reader

      public BufferedReader reader(int bufferSize)
      Returns a buffered reader for reading this file as characters.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • reader

      public BufferedReader reader(int bufferSize, String charset)
      Returns a buffered reader for reading this file as characters.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • readString

      public String readString()
      Reads the entire file into a string using the platform's default charset.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • readString

      public String readString(String charset)
      Reads the entire file into a string using the specified charset.
      Parameters:
      charset - If null the default charset is used.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • readBytes

      public byte[] readBytes()
      Reads the entire file into a byte array.
      Throws:
      ArcRuntimeException - if the file handle represents a directory, doesn't exist, or could not be read.

    • readByteStream

      public ByteArrayInputStream readByteStream()
      Returns:
      a new ByteArrayInputStream containing all the bytes in this file.

    • readBytes

      public int readBytes(byte[] bytes, int offset, int size)
      Reads the entire file into the byte array. The byte array must be big enough to hold the file's data.
      Parameters:
      bytes - the array to load the file into
      offset - the offset to start writing bytes
      size - the number of bytes to read, see length()
      Returns:
      the number of read bytes

    • map

      public ByteBuffer map()
      Attempts to memory map this file in READ_ONLY mode. Android files must not be compressed.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, doesn't exist, or could not be read, or memory mapping fails, or is a Files.classpath(java.lang.String) file.

    • map

      public ByteBuffer map(FileChannel.MapMode mode)
      Attempts to memory map this file. Android files must not be compressed.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, doesn't exist, or could not be read, or memory mapping fails, or is a Files.classpath(java.lang.String) file.

    • writes

      public Writes writes(boolean append)

    • writes

      public Writes writes()

    • reads

      public Reads reads()

    • writesDeflate

      public Writes writesDeflate()

    • readsDeflate

      public Reads readsDeflate()

    • write

      public OutputStream write()

    • write

      public OutputStream write(boolean append)
      Returns a stream for writing to this file. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • write

      public OutputStream write(boolean append, int bufferSize)
      Returns a buffered stream for writing to this file. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      bufferSize - The size of the buffer.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • write

      public void write(InputStream input, boolean append)
      Reads the remaining bytes from the specified stream and writes them to this file. The stream is closed. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writer

      public Writer writer(boolean append)
      Returns a writer for writing to this file using the default charset. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writer

      public Writer writer(boolean append, String charset)
      Returns a writer for writing to this file. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      charset - May be null to use the default charset.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writePng

      public void writePng(Pixmap pixmap)

    • writeString

      public void writeString(String string)
      Writes a string without appending it.
      See Also:

    • writeString

      public void writeString(String string, boolean append)
      Writes the specified string to the file using the default charset. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writeString

      public void writeString(String string, boolean append, String charset)
      Writes the specified string to the file using the specified charset. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      charset - May be null to use the default charset.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writeBytes

      public void writeBytes(byte[] bytes)

    • writeBytes

      public void writeBytes(byte[] bytes, boolean append)
      Writes the specified bytes to the file. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • writeBytes

      public void writeBytes(byte[] bytes, int offset, int length, boolean append)
      Writes the specified bytes to the file. Parent directories will be created if necessary.
      Parameters:
      append - If false, this file will be overwritten if it exists, otherwise it will be appended.
      Throws:
      ArcRuntimeException - if this file handle represents a directory, if it is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or if it could not be written.

    • walk

      public void walk(Cons<Fi> cons)
      Recursively iterates through all files in this directory. Directories are not handled.

    • findAll

      public Seq<Fi> findAll(Boolf<Fi> test)
      Recursively iterates through all files in this directory and adds them to an array. Directories are not handled.

    • findAll

      public Seq<Fi> findAll()
      Recursively iterates through all files in this directory and adds them to a newly allocated array.

    • seq

      public Seq<Fi> seq()
      Equivalent to list(), but returns a Seq.

    • list

      public Fi[] list()
      Returns the paths to the children of this directory. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.internal(java.lang.String) handle to a directory on the classpath will return a zero length array.
      Throws:
      ArcRuntimeException - if this file is an Files.classpath(java.lang.String) file.

    • list

      public Fi[] list(FileFilter filter)
      Returns the paths to the children of this directory that satisfy the specified filter. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.internal(java.lang.String) handle to a directory on the classpath will return a zero length array.
      Parameters:
      filter - the FileFilter to filter files
      Throws:
      ArcRuntimeException - if this file is an Files.classpath(java.lang.String) file.

    • list

      public Fi[] list(FilenameFilter filter)
      Returns the paths to the children of this directory that satisfy the specified filter. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.internal(java.lang.String) handle to a directory on the classpath will return a zero length array.
      Parameters:
      filter - the FilenameFilter to filter files
      Throws:
      ArcRuntimeException - if this file is an Files.classpath(java.lang.String) file.

    • list

      public Fi[] list(String suffix)
      Returns the paths to the children of this directory with the specified suffix. Returns an empty list if this file handle represents a file and not a directory. On the desktop, an Files.internal(java.lang.String) handle to a directory on the classpath will return a zero length array.
      Throws:
      ArcRuntimeException - if this file is an Files.classpath(java.lang.String) file.

    • isDirectory

      public boolean isDirectory()
      Returns true if this file is a directory. Always returns false for classpath files. On Android, an Files.internal(java.lang.String) handle to an empty directory will return false. On the desktop, an Files.internal(java.lang.String) handle to a directory on the classpath will return false.

    • child

      public Fi child(String name)
      Returns a handle to the child with the specified name.

    • sibling

      public Fi sibling(String name)
      Returns a handle to the sibling with the specified name.
      Throws:
      ArcRuntimeException - if this file is the root.

    • parent

      public Fi parent()

    • mkdirs

      public boolean mkdirs()
      Throws:
      ArcRuntimeException - if this file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • exists

      public boolean exists()
      Returns true if the file exists. On Android, a Files.classpath(java.lang.String) or Files.internal(java.lang.String) handle to a directory will always return false. Note that this can be very slow for internal files on Android!

    • delete

      public boolean delete()
      Deletes this file or empty directory and returns success. Will not delete a directory that has children.
      Throws:
      ArcRuntimeException - if this file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • deleteDirectory

      public boolean deleteDirectory()
      Deletes this file or directory and all children, recursively.
      Throws:
      ArcRuntimeException - if this file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • emptyDirectory

      public void emptyDirectory()
      Deletes all children of this directory, recursively.
      Throws:
      ArcRuntimeException - if this file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • emptyDirectory

      public void emptyDirectory(boolean preserveTree)
      Deletes all children of this directory, recursively. Optionally preserving the folder structure.
      Throws:
      ArcRuntimeException - if this file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • copyTo

      public void copyTo(Fi dest)
      Copies this file or directory to the specified file or directory. If this handle is a file, then 1) if the destination is a file, it is overwritten, or 2) if the destination is a directory, this file is copied into it, or 3) if the destination doesn't exist, mkdirs() is called on the destination's parent and this file is copied into it with a new name. If this handle is a directory, then 1) if the destination is a file, ArcRuntimeException is thrown, or 2) if the destination is a directory, this directory is copied into it recursively, overwriting existing files, or 3) if the destination doesn't exist, mkdirs() is called on the destination and this directory is copied into it recursively.
      Throws:
      ArcRuntimeException - if the destination file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file, or copying failed.

    • copyFilesTo

      public void copyFilesTo(Fi dest)
      Copies the contents of this folder into another folder. Unlike copyTo, this only copies the *contents*, not this folder itself.
      Throws:
      ArcRuntimeException - if this or is not a valid directory, or copying fails.

    • moveTo

      public void moveTo(Fi dest)
      Moves this file to the specified file, overwriting the file if it already exists.
      Throws:
      ArcRuntimeException - if the source or destination file handle is a Files.classpath(java.lang.String) or Files.internal(java.lang.String) file.

    • length

      public long length()
      Returns the length in bytes of this file, or 0 if this file is a directory, does not exist, or the size cannot otherwise be determined.

    • lastModified

      public long lastModified()
      Returns the last modified time in milliseconds for this file. Zero is returned if the file doesn't exist. Zero is returned for Files.classpath(java.lang.String) files. On Android, zero is returned for Files.internal(java.lang.String) files. On the desktop, zero is returned for Files.internal(java.lang.String) files on the classpath.

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object