# Class: com.pnfsoftware.jeb.util.io.IO

File manipulation utility routines.

## Constructor: IO


## Static Field: MAX_FILENAME_SIZE
Type: `int`

Constant value: `255`
Description: Maximum filename size used in JEB \(255 allowed for Linux, 259 for Windows file\)

## Static Field: MAX_PATH_SIZE
Type: `int`

Constant value: `248`
Description: Maximum foldername size used in JEB \(248 for Windows folder\)

## Static Method: abs
- parameter: `file`, type: `java.io.File`
- return type: `java.lang.String`

Description: Provide an absolute simplified path. This method is OS\-dependent. 

 Rules:
 \- `.` and `..` uses are resolved.
 \- Multiple\-path separator uses such as `///` or `\\` are resolved.
 \- Redundant trailing separators are removed.
 \- The empty path is always resolved to `.`.
 \- If the FS is case\-insensitive \(e.g. NTFS\), the case is **not** standardized \(Windows\).
 \- Symbolic links are not resolved.
parameter: file: input file
return: absolute simplified path

## Static Method: abs
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Provide an absolute simplified path. This method is similar to [File#getCanonicalFile()](File#getCanonicalFile()), except that it does not resolve symlinks \(and therefore, does not throw [IOException](IOException).\) 

 Rules:
 \- `.` and `..` uses are resolved.
 \- Multiple\-path separator uses such as `///` or `\\` are resolved.
 \- Redundant trailing separators are removed.
 \- The empty path is always resolved to `.`.
 \- If the FS is case\-insensitive \(e.g. NTFS\), the case is **not** standardized \(Windows\).
 \- Symbolic links are not resolved.
parameter: path: input path
return: absolute simplified path

## Static Method: addFileToJar
- parameter: `jar`, type: `java.util.jar.JarOutputStream`
- parameter: `file`, type: `java.io.File`
- parameter: `entryName`, type: `java.lang.String`

Description: Add a new entry to a jar output stream.
parameter: jar: destination jar stream
parameter: file: source file
parameter: entryName: archive entry name
throws: on IO error

## Static Method: addFileToZip
- parameter: `zip`, type: `java.util.zip.ZipOutputStream`
- parameter: `file`, type: `java.io.File`
- parameter: `entryName`, type: `java.lang.String`

Description: Add a new entry to a zip output stream.
parameter: zip: destination zip stream
parameter: file: source file
parameter: entryName: archive entry name
throws: on IO error

## Static Method: basename
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Return the base name of the provided path. The base name is the part of the path that follows the last file separator character \(slash or backslash\). No further processing is done. The returned string may be empty or blank. It does not contain slash or backslash. 

 Implementation note: mirrors Python 3's `os.path.basename`.
parameter: path: a path
return: never null

## Static Method: checkFileFreshness
- parameter: `file`, type: `java.io.File`
- parameter: `millis`, type: `long`
- parameter: `cleanStaleFile`, type: `boolean`
- return type: `boolean`

Description: 
parameter: file: file to check
parameter: millis: freshness threshold in milliseconds
parameter: cleanStaleFile: true to delete stale files
return: true if the file exists and its last modification timestamp is less than         `millis` ms old

## Static Method: compareFiles
- parameter: `file0`, type: `java.io.File`
- parameter: `file1`, type: `java.io.File`
- return type: `boolean`

Description: Compare the contents of two files for equality.
parameter: file0: first file
parameter: file1: second file
throws: one of the input file is not found
throws: other IO exception

## Static Method: compressFolder
- parameter: `folderPath`, type: `java.lang.String`
- parameter: `zipfilePath`, type: `java.lang.String`
- return type: `boolean`

Description: Compress a folder and its contents to a zip archive.
parameter: folderPath: input folder
parameter: zipfilePath: output zip file
return: true on success

## Static Method: compressFolder
- parameter: `folder`, type: `java.io.File`
- parameter: `zipfile`, type: `java.io.File`
- return type: `boolean`

Description: Compress a folder and its contents to a zip archive.
parameter: folder: input folder
parameter: zipfile: output zip file
return: true on success

## Static Method: copy
- parameter: `input`, type: `java.io.InputStream`
- parameter: `output`, type: `java.io.OutputStream`
- return type: `long`

Description: 
deprecated: use [#copyStream(InputStream, OutputStream)](#copyStream(InputStream, OutputStream))

## Static Method: copyAsync
- parameter: `input`, type: `java.io.InputStream`
- parameter: `output`, type: `java.io.OutputStream`
- return type: `java.lang.Thread`

Description: Copy a continuous stream of data from a source to a destination. This method creates a thread; it is non\-blocking and returns immediately.
parameter: input: the source input stream
parameter: output: the destination output stream
return: the daemon worker thread in charge of copying the data

## Static Method: copyFile
- parameter: `src`, type: `java.io.File`
- parameter: `dst`, type: `java.io.File`
- parameter: `overwrite`, type: `boolean`

Description: Copy a source file to a destination. The copy process is interruptible.
parameter: src: source file \(not a directory\)
parameter: dst: destination file or directory
parameter: overwrite: if true, the destination file may be overwritten if it already exists
throws: the source is not found
throws: the destination would be overwritten
throws: other IO exception

## Static Method: copyStream
- parameter: `input`, type: `java.io.InputStream`
- parameter: `output`, type: `java.io.OutputStream`
- parameter: `buffer`, type: `byte[]`
- return type: `long`

Description: Read bytes from an input stream and dump them to an output stream. The copy process is interruptible.
parameter: input: source stream
parameter: output: destination stream
parameter: buffer: recommended use: multiple of 0x1000
return: number of bytes copied
throws: if copying fails or is interrupted

## Static Method: copyStream
- parameter: `input`, type: `java.io.InputStream`
- parameter: `output`, type: `java.io.OutputStream`
- return type: `long`

Description: Read bytes from an input stream and dump them to an output stream. The copy process is interruptible.
parameter: input: source stream
parameter: output: destination stream
return: number of bytes copied
throws: if copying fails or is interrupted

## Static Method: createDirectory
- parameter: `path`, type: `java.lang.String`
- return type: `boolean`

Description: Safely create a directory.
parameter: path: directory path
return: true on success, else false

## Static Method: createDirectory
- parameter: `f`, type: `java.io.File`
- return type: `boolean`

Description: Safely create a directory.
parameter: f: directory to create
return: true on success, else false

## Static Method: createFile
- parameter: `file`, type: `java.io.File`
- parameter: `createDirs`, type: `boolean`
- return type: `boolean`

Description: Create an empty file.
parameter: file: file to create
parameter: createDirs: if true, the directory structure needed to contain the file will also be            created
return: true if the named file does not exist and was successfully created; false if the         named file already exists
throws: if the file cannot be created

## Static Method: createFolder
- parameter: `path`, type: `java.lang.String`
- return type: `java.io.File`

Description: Create or retrieve a directory.
parameter: path: directory path
return: the directory file object
throws: on creation error

## Static Method: createFoldersForFile
- parameter: `file`, type: `java.io.File`

Description: Create the directory structure needed to store a file.
parameter: file: a file
throws: if a parent directory cannot be created

## Static Method: createSafeTempFile
- return type: `java.io.File`

Description: Create an empty file in the safe temporary area.
return: the file
throws: on file creation error

## Static Method: createTempFile
- return type: `java.io.File`

Description: Create an empty file in the temporary folder.
return: the file
throws: on file creation error

## Static Method: createTempFile
- parameter: `basename`, type: `java.lang.String`
- parameter: `extension`, type: `java.lang.String`
- return type: `java.io.File`

Description: Create a file in the default temp folder.
parameter: basename: optional base name
parameter: extension: optional extension \(suffix\)
return: created temporary file
throws: on file creation error

## Static Method: createTempFile
- parameter: `exactname`, type: `java.lang.String`
- return type: `java.io.File`

Description: Create a file \(with an exact name\) in the default temp folder.
parameter: exactname: exact file name
return: the file object \(the file itself may or may not exist when the method returns\)

## Static Method: createTempFileNumbered
- parameter: `name`, type: `java.lang.String`
- return type: `java.io.File`

Description: Create a new file with the provided name in the default temp folder. If a file with the provided name already exists, counter\-suffixed names are tried \(`NAME.1`, `NAME.2`, etc.\) until the first non\-existent entry is found.
parameter: name: desired file name
return: the file object \(the file itself does not exist at the time this method returns\)
throws: if a free numbered name cannot be found

## Static Method: createTempFolder
- parameter: `folderName`, type: `java.lang.String`
- return type: `java.io.File`

Description: Create a directory in the default temporary\-file directory.
parameter: folderName: optional folder name; if null, a randomly named folder will be created
return: a File representing the newly created directory, or null on error
throws: if an IO exception happened

## Static Method: deleteDirectory
- parameter: `path`, type: `java.lang.String`
- return type: `boolean`

Description: Delete a directory and its contents recursively.
parameter: path: directory path
return: true on success

## Static Method: deleteDirectory
- parameter: `dir`, type: `java.io.File`
- return type: `boolean`

Description: Delete a directory and its contents recursively.
parameter: dir: directory to delete
return: true on success, false if errors were encountered; note that some files and         directories may have been deleted

## Static Method: deleteDirectoryContents
- parameter: `dir`, type: `java.io.File`
- return type: `boolean`

Description: Delete a directory contents recursively \(ie, clear the directory\). The directory itself is not deleted.
parameter: dir: directory whose contents should be deleted
return: true on success, false if errors were encountered; note that some files and         directories may have been deleted

## Static Method: deleteDirectoryOnExit
- parameter: `dir`, type: `java.io.File`

Description: Delete a folder and all its contents recursively, when the virtual machine terminates.
parameter: dir: folder to be deleted

## Static Method: deleteFile
- parameter: `file`, type: `java.io.File`
- return type: `boolean`

Description: Delete a file.
parameter: file: the file to be deleted
return: true on success

## Static Method: dirname
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Return the directory name of the provided path. The returned string may be empty. It will is not terminated by slash or backslash. 

 Implementation note: mirrors Python 3's `os.path.dirname`.
parameter: path: a path
return: never null

## Static Method: escapeFileName
- parameter: `filename`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Escape filename invalid characters with an underscore. 

 For proper path sanitization, use [#sanitizePath(String, boolean, boolean)](#sanitizePath(String, boolean, boolean)).
parameter: filename: to escape
return: the escaped filename

## Static Method: escapeFileName
- parameter: `filename`, type: `java.lang.String`
- parameter: `newChar`, type: `char`
- return type: `java.lang.String`

Description: Escape illegal characters in filename by the provided char. Note than this is a black\-list escaper \(whitelist character would be too costly to manage any char\) so file name can still be irrelevant on the target Operating System. The list of excluded characters are `:`, `\`, `/`, `*`, `"`, `?`, `|`, `<`, and `>`, which covers most of the invalid characters. 

 For proper path sanitization, use [#sanitizePath(String, boolean, boolean)](#sanitizePath(String, boolean, boolean)).
parameter: filename: to escape
parameter: newChar: replacement character
return: the escaped filename

## Static Method: escapeFileNameStrict
- parameter: `filename`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Create a valid filename with an underscore for non alphanumeric char, '\-', '\_', '.' nor '''. 

 For proper path sanitization, use [#sanitizePath(String, boolean, boolean)](#sanitizePath(String, boolean, boolean)).
parameter: filename: to escape
return: the escaped filename

## Static Method: escapeFileNameStrict
- parameter: `filename`, type: `java.lang.String`
- parameter: `newChar`, type: `char`
- return type: `java.lang.String`

Description: Create a valid filename from any string. Compared to [#escapeFileName(String, char)](#escapeFileName(String, char)), this is a white\-list escaper so generated filename will be legal on any non\-exotic target Operating System. The list of allowed characters are any alphanumeric char, '\-', '\_', '.', '''. 

 For proper path sanitization, use [#sanitizePath(String, boolean, boolean)](#sanitizePath(String, boolean, boolean)).
parameter: filename: to escape
parameter: newChar: replacement character
return: the escaped filename

## Static Method: expandPath
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Perform expansion of certain shell artifacts used in path names. 

 Currently, the expansions performed are: 
 
- a leading tilde is expanded to a user's home directory
-
parameter: path: input path
return: a full path name, if possible \- otherwise, the original path is returned

## Static Method: extractToFolder
- parameter: `inputZipFile`, type: `java.io.File`
- parameter: `outputFolder`, type: `java.io.File`

Description: Extract the contents of a zip archive to a target folder.
parameter: inputZipFile: input zip file path
parameter: outputFolder: output folder directory
throws: if an error occurred; the current state of extraction within the target             folder is not erased

## Static Method: getCwd
- return type: `java.lang.String`

Description: Get the path of the current working directory.
return: current working directory path

## Static Method: getExtension
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Extract the extension of a file path.
parameter: path: a path
return: the extension \(always starting with a dot\), or the empty string

## Static Method: getExtension
- parameter: `file`, type: `java.io.File`
- return type: `java.lang.String`

Description: Extract the extension of a file path.
parameter: file: a file
return: the extension \(always starting with a dot\), or the empty string

## Static Method: getFirstByte
- parameter: `path`, type: `java.lang.String`
- return type: `byte`

Description: Get the first byte of a file. This method never throws exceptions. If an error occurs, 0 is returned. It is up to the client to handle that special case.
parameter: path: input file path
return: first byte, or 0 on error

## Static Method: getFirstIntLE
- parameter: `path`, type: `java.lang.String`
- return type: `int`

Description: Get the first 4\-byte of a file, read as a little\-endian integer. This method never throws exceptions. If an error occurs, 0 is returned. It is up to the client to handle that special case.
parameter: path: file path
return: the first int, 0 on error

## Static Method: getFirstLongLE
- parameter: `file`, type: `java.io.File`
- return type: `long`

Description: Get the first 8\-byte of a file, read as a little\-endian long. This method never throws exceptions. If an error occurs, 0 is returned. It is up to the client to handle that special case.
parameter: file: input file
return: the first long, 0 on error

## Static Method: getFirstShortLE
- parameter: `path`, type: `java.lang.String`
- return type: `short`

Description: Get the first 2\-byte of a file, read as a little\-endian short. This method never throws exceptions. If an error occurs, 0 is returned. It is up to the client to handle that special case.
parameter: path: input file path
return: first two bytes interpreted as a little\-endian short, or 0 on error

## Static Method: getHomeFolder
- return type: `java.io.File`

Description: Retrieve the current user's home folder.
return: current user's home folder

## Static Method: getOriginalCwd
- return type: `java.lang.String`

Description: Get original working directory, i.e. the value of the current directory set by the JVM when the program was started. 

 This method is unreliable. It assumes that all updates to the current directory are done through [this class](#setCwd(String)).
return: original working directory path

## Static Method: getParentFile2
- parameter: `file`, type: `java.io.File`
- return type: `java.io.File`

Description: A safer implementation of [File#getParentFile()](File#getParentFile()). If the input file is a single\-level relative path \(eg, "abc"\), this method will first retrieve the absolute path \(relative to the current folder\) before trying to retrieve the parent folder.
parameter: file: file or folder
return: null if there is no parent folder, eg in the case of a root folder

## Static Method: getRelativePath
- parameter: `file`, type: `java.io.File`
- parameter: `base`, type: `java.io.File`
- return type: `java.lang.String`

Description: Provide the path to a file relative to a base. This method is similar to [#isRootedIn(File, File)](#isRootedIn(File, File)); one difference is that the canonicalization of the provided Files is done with [#abs(File)](#abs(File)), which does not resolve symlinks.
parameter: file: a file or folder
parameter: base: the base folder
return: null if \`file\` is not rooted in \`base\`; else, the relative path of \`file\` \(relative         to \`base\`\)

## Static Method: getSessionTemporaryFolder
- return type: `java.io.File`

Description: Retrieve the JEB session\-specific temporary folder. That folder is unique per session, and can be used to drop additional temporary files and folders. Its contents is deleted when the session ends \(i.e. when the owning JEB instance is terminated\).
return: this JEB session's temporary folder

## Static Method: getTempFolder
- return type: `java.io.File`

Description: Retrieve the temporary folder.
return: the temp folder, never null

## Static Method: inFolder
- parameter: `file`, type: `java.io.File`
- parameter: `folder`, type: `java.io.File`
- return type: `boolean`

Description: Determine if a hypothetical file would be contained within a hypothetical folder, i.e. whether or not the folder would be an ancestor of the file.
parameter: file: file or folder to test \(whose existence is not required\)
parameter: folder: candidate ancestor folder \(whose existence is not required\)
return: true if the candidate folder looks like an ancestor folder of the file

## Static Method: isFile
- parameter: `path`, type: `java.lang.String`
- return type: `boolean`

Description: Determine if a path refers to an existing file.
parameter: path: path to test
return: true if the path exists and is a regular file

## Static Method: isRootedIn
- parameter: `file`, type: `java.io.File`
- parameter: `base`, type: `java.io.File`
- parameter: `canonicalFiles`, type: `boolean`
- return type: `boolean`

Description: Determine if a file or folder is rooted in a base folder. 

 This method is potentially unsafe if canonicalFiles is true but the provided File objects are not\!
parameter: file: file or folder to check
parameter: base: base folder
parameter: canonicalFiles: if true, the provided File objects must be            [canonical](File#getCanonicalFile())
return: true if the file is rooted in base
throws: may be thrown when canonicalizing Files

## Static Method: isRootedIn
- parameter: `file`, type: `java.io.File`
- parameter: `base`, type: `java.io.File`
- return type: `boolean`

Description: Determine if a file or folder is rooted in a base folder.
parameter: file: file or folder to check
parameter: base: base folder
return: true if the file is rooted in base
throws: may be thrown when canonicalizing Files

## Static Method: listFiles
- parameter: `folderpath`, type: `java.lang.String`
- return type: `java.util.List<java.io.File>`

Description: Recursively do a directory listing. The list returned is a list of true files \(not directories\). Refer to the [DirectoryEnumerator](DirectoryEnumerator) object for a more powerful file enumerator.
parameter: folderpath: folder path
return: the list of absolute file paths

## Static Method: listFiles
- parameter: `folder`, type: `java.io.File`
- return type: `java.util.List<java.io.File>`

Description: Recursively do a directory listing. The list returned is a list of true files \(not directories\). Refer to the [DirectoryEnumerator](DirectoryEnumerator) object for a more powerful file enumerator.
parameter: folder: folder to list
return: the list of absolute files

## Static Method: noExtension
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Remove the extension from a file path.
parameter: path: input path
return: path without its extension

## Static Method: noExtension
- parameter: `file`, type: `java.io.File`
- return type: `java.io.File`

Description: Remove the extension from a file path.
parameter: file: input file
return: file without its extension

## Static Method: parsePathElements
- parameter: `s`, type: `java.lang.String`
- return type: `java.util.List<java.lang.String>`

Description: Parse the elements of a path.
parameter: s: a path
return: a list of path elements, possibly empty

## Static Method: processInputStream
- parameter: `in`, type: `java.io.InputStream`
- parameter: `consumer`, type: `java.util.function.BiConsumer<byte[],java.lang.Integer>`

Description: Process an input stream. The method returns after all input bytes are read.
parameter: in: input stream \(it will be read via a [BufferedInputStream](BufferedInputStream)\)
parameter: consumer: the consumer of read data: first input= bytes array; second input: the count            of bytes read
throws: on IO error

## Static Method: readFile
- parameter: `file`, type: `java.io.File`
- parameter: `maxAllowedSize`, type: `long`
- return type: `byte[]`

Description: Read the contents of a binary file that is at most 2 Gb.
parameter: file: file to read
parameter: maxAllowedSize: optional maximum size, \-1 means the max \(2 Gb\)
return: the contents of the file
throws: on IO error, or if the read size exceeds the limit

## Static Method: readFile
- parameter: `file`, type: `java.io.File`
- return type: `byte[]`

Description: Read the contents of a binary file that is at most 2 Gb.
parameter: file: file to read
return: the contents of the file
throws: on IO error, or if the read size exceeds 2 Gb

## Static Method: readFile
- parameter: `path`, type: `java.lang.String`
- return type: `byte[]`

Description: Read the contents of a binary file.
parameter: path: input file path
return: file contents
throws: on IO error, or if the read size exceeds 2 Gb

## Static Method: readFileSafe
- parameter: `file`, type: `java.io.File`
- return type: `byte[]`

Description: Read a binary file safely. If any error happens, an empty array is returned.
parameter: file: input file
return: the bytes in the file, never null \(empty array on error\)

## Static Method: readInputLine
- return type: `java.lang.String`

Description: Read a line from the standard input.
return: input line
throws: on IO error

## Static Method: readInputLine
- parameter: `msg`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Read a line from the standard input.
parameter: msg: optional message sent to stdout before waiting for input
return: input line
throws: on IO error

## Static Method: readInputLineSafe
- return type: `java.lang.String`

Description: Read a line from the standard input. This method is safe to use; it does not raise, instead returning a null string on error.
return: input line, or null on error

## Static Method: readInputStream
- parameter: `in`, type: `java.io.InputStream`
- return type: `byte[]`

Description: Read and reliably return all bytes of an input stream. The stream must be less than 2Gb. The caller is responsible for closing the input stream after reading.
parameter: in: input stream
return: stream contents
throws: on IO error, or if the read size exceeds 2 Gb

## Static Method: readLines
- parameter: `input`, type: `java.io.InputStream`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `java.util.List<java.lang.String>`

Description: Read the contents of a stream as a line of strings.
parameter: input: the input stream
parameter: encoding: the stream encoding
return: a list of strings, without new\-line characters
throws: on IO error

## Static Method: readLines
- parameter: `input`, type: `java.io.InputStream`
- return type: `java.util.List<java.lang.String>`

Description: Read the contents of a stream as a text buffer of UTF\-8 encoded strings.
parameter: input: input stream
return: a list of strings, without new\-line characters
throws: on IO error

## Static Method: readLines
- parameter: `file`, type: `java.io.File`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `java.util.List<java.lang.String>`

Description: Read the lines of a text file.
parameter: file: input file
parameter: encoding: file encoding
return: a list of strings, without new\-line characters
throws: on IO error

## Static Method: readLines
- parameter: `file`, type: `java.io.File`
- return type: `java.util.List<java.lang.String>`

Description: Read the UTF\-8 encoded lines of a text file.
parameter: file: input file
return: a list of strings, without new\-line characters
throws: on IO error

## Static Method: readLinesSafe
- parameter: `file`, type: `java.io.File`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `java.util.List<java.lang.String>`

Description: Read the lines of a text file. On error, the method returns null.
parameter: file: input file
parameter: encoding: file encoding
return: a list of lines without newline chars, null on error

## Static Method: readLinesSafe
- parameter: `file`, type: `java.io.File`
- return type: `java.util.List<java.lang.String>`

Description: Read the lines of a UTF8 encoded text file. On error, the method returns null.
parameter: file: input file
return: a list of lines without newline chars, null on error

## Static Method: readTextFile
- parameter: `file`, type: `java.io.File`
- return type: `java.lang.String`

Description: Read a file and decode it to a string using the system's default encoding.
parameter: file: input file
return: decoded text
throws: on IO error

## Static Method: readTextFile
- parameter: `file`, type: `java.io.File`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `java.lang.String`

Description: Read a file and decode it to a string using the system's default locale.
parameter: file: input file
parameter: encoding: requested encoding \(if null, the system's default encoding is used\)
return: decoded text
throws: on IO error

## Static Method: renameFile
- parameter: `src`, type: `java.io.File`
- parameter: `dst`, type: `java.io.File`
- parameter: `mode`, type: `int`
- return type: `boolean`

Description: Rename a file with options.
parameter: src: source file
parameter: dst: destination
parameter: mode: define the mechanics of the renaming operations:            
            
- 0: standard rename, fail if 'dst' already exists or 'src' does not exist
-             
- 1: overwrite 'dst' if 'dst' already exists
-             
- 2: delete 'src' if 'dst' already exists
-
return: true on success

## Static Method: replaceExtension
- parameter: `file`, type: `java.io.File`
- parameter: `extension`, type: `java.lang.String`
- return type: `java.io.File`

Description: 
parameter: file: input file
parameter: extension: the new extension, eg ".xyz"
return: file with the new extension

## Static Method: safeList
- parameter: `f`, type: `java.io.File`
- return type: `java.lang.String[]`

Description: A safe version of [File#list()](File#list()).
parameter: f: a non\-null file object
return: non null array

## Static Method: safeList
- parameter: `f`, type: `java.io.File`
- parameter: `filter`, type: `java.io.FilenameFilter`
- return type: `java.lang.String[]`

Description: A safe version of [File#list(FilenameFilter)](File#list(FilenameFilter)).
parameter: f: a non\-null file object
parameter: filter: a file filter
return: non\-null array

## Static Method: safeListFiles
- parameter: `f`, type: `java.io.File`
- return type: `java.io.File[]`

Description: A safe version of [File#listFiles()](File#listFiles()).
parameter: f: a non\-null file object
return: non null array

## Static Method: safeListFiles
- parameter: `f`, type: `java.io.File`
- parameter: `filter`, type: `java.io.FileFilter`
- return type: `java.io.File[]`

Description: A safe version of [File#listFiles(FileFilter)](File#listFiles(FileFilter)).
parameter: f: a non\-null file object
parameter: filter: a file filter
return: non\-null array

## Static Method: sanitizePath
- parameter: `path`, type: `java.lang.String`
- parameter: `isSinglePathElement`, type: `boolean`
- parameter: `replaceBlankCharacters`, type: `boolean`
- return type: `java.lang.String`

Description: Sanitize a path. **The returned path is guaranteed to be legal on the current filesystem \(FS\) if and only if the element being sanitized is a single path element.** For full paths elements, sanitization cannot be guaranteed because some characters which could yield to bad paths, cannot be safely sanitized. 

 Notes:
 \- the following characters are always sanitized: `? % * | < > "`
 \- if a single path element is provided, the following characters are sanitized as well: `/ \ :`
parameter: path: a path \(absolute or not\)
parameter: isSinglePathElement: true if the provided path should be treated as a single path            element, allowing more aggressive replacements
parameter: replaceBlankCharacters: if true, sanitize all blank characters \(per the Unicode            definition of a blank character\) as well, even though some may be legal
return: a sanitized path, never null, guaranteed to be valid on the current FS

## Static Method: sanitizePathUnsafe
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Attempt to sanitize a path. 

 Under some conditions, the returned path may be unsafe, eg on Windows: the sanitization of a path like "x::z" will generate an unsafe path. You must use [#sanitizePath(String, boolean, boolean)](#sanitizePath(String, boolean, boolean)) to guarantee sanitization.
parameter: path: input path
return: sanitized path

## Static Method: setCwd
- parameter: `cwd`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Set the path of the current working directory. 

 Note: handle with care, changing the CWD may not impact all subsequent file read and write operations. It is safer to retrieve and use the CWD with [#getCwd()](#getCwd()).
parameter: cwd: new current working directory
return: previous working directory

## Static Method: simplifyPath
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: Simplify a path. This method is OS\-dependent. To call a specific \(Unix or Windows\) version of this method, use [#simplifyPathUnix(String)](#simplifyPathUnix(String)) or [#simplifyPathWindows(String)](#simplifyPathWindows(String)). 

 Rules:
 \- `.` and `..` uses are resolved.
 \- Multiple\-path separator uses such as `///` or `\\` are resolved.
 \- Redundant trailing separators are removed.
 \- The empty path is always resolved to `.`.
 \- If the FS is case\-insensitive \(e.g. NTFS\), the case is **not** standardized \(Windows\).
 \- Symbolic links are not resolved.
parameter: path: input path
return: absolute simplified path

## Static Method: simplifyPathUnix
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: See [#simplifyPath(String)](#simplifyPath(String)).

## Static Method: simplifyPathWindows
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String`

Description: See [#simplifyPath(String)](#simplifyPath(String)).

## Static Method: splitExtension
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Split a file path into its extension\-less part and its extension.
parameter: path: a file path
return: a 2\-element string array; the extension, if any, is the second element and always         start with '.' unless it's empty

## Static Method: splitPath
- parameter: `path`, type: `java.lang.String`
- return type: `java.lang.String[]`

Description: Split a path into its base part and its filename part. 

 Unlike [File#getName()](File#getName()), this method considers both slash and backslash to be valid path separators.
parameter: path: input path
return: a two\-element array: the first element contains the base and may be empty \(if         non\-empty, it will always end by a separator\); the second element is the name, which         does not contain any separator

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `size`, type: `int`
- parameter: `createDirs`, type: `boolean`

Description: Write data to a file whose containing directory structure may not exist. Existing file contents will be overwritten.
parameter: file: output file
parameter: data: source bytes
parameter: offset: first source byte to write
parameter: size: number of bytes to write
parameter: createDirs: create the intermediate directories if need be
throws: if the file cannot be written

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`
- parameter: `createDirs`, type: `boolean`

Description: Write data to a file whose containing directory structure may not exist. Existing file contents will be overwritten.
parameter: file: output file
parameter: data: source bytes
parameter: createDirs: create the intermediate directories if need be
throws: if the file cannot be written

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `size`, type: `int`

Description: Write data to a file. Existing file contents will be overwritten.
parameter: file: output file
parameter: data: source bytes
parameter: offset: first source byte to write
parameter: size: number of bytes to write
throws: if the file cannot be written

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`

Description: Write data to a file. Existing file contents will be overwritten.
parameter: file: destination file
parameter: data: binary data to write
throws: on error

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `str`, type: `java.lang.String`

Description: 
deprecated: use [#writeTextFile(File, String)](#writeTextFile(File, String))

## Static Method: writeFile
- parameter: `file`, type: `java.io.File`
- parameter: `str`, type: `java.lang.String`
- parameter: `charsetName`, type: `java.lang.String`

Description: 
deprecated: use [#writeTextFile(File, String, String)](#writeTextFile(File, String, String))

## Static Method: writeFileSafe
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`
- parameter: `offset`, type: `int`
- parameter: `size`, type: `int`
- parameter: `createDirs`, type: `boolean`
- return type: `boolean`

Description: Write a binary file safely.
parameter: file: output file
parameter: data: source bytes
parameter: offset: first source byte to write
parameter: size: number of bytes to write
parameter: createDirs: create the intermediate directories if need be
return: true on success

## Static Method: writeFileSafe
- parameter: `file`, type: `java.io.File`
- parameter: `data`, type: `byte[]`
- parameter: `createDirs`, type: `boolean`
- return type: `boolean`

Description: Write a binary file safely.
parameter: file: output file
parameter: data: source bytes
parameter: createDirs: create the intermediate directories if need be
return: true on success

## Static Method: writeLines
- parameter: `output`, type: `java.io.OutputStream`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- parameter: `encoding`, type: `java.nio.charset.Charset`

Description: Write strings.
parameter: output: output stream
parameter: lines: lines to write
parameter: encoding: output encoding
throws: on IO error

## Static Method: writeLines
- parameter: `output`, type: `java.io.OutputStream`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`

Description: Write UTF\-8 encoded strings.
parameter: output: output stream
parameter: lines: lines to write
throws: on IO error

## Static Method: writeLines
- parameter: `file`, type: `java.io.File`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- parameter: `encoding`, type: `java.nio.charset.Charset`

Description: Write strings.
parameter: file: output file
parameter: lines: lines to write
parameter: encoding: output encoding
throws: on IO error

## Static Method: writeLines
- parameter: `file`, type: `java.io.File`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`

Description: Write UTF\-8 encoded strings.
parameter: file: output file
parameter: lines: lines to write
throws: on IO error

## Static Method: writeLinesSafe
- parameter: `output`, type: `java.io.OutputStream`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `boolean`

Description: Write strings. On error, the method returns false.
parameter: output: output stream
parameter: lines: lines to write
parameter: encoding: output encoding
return: true on success

## Static Method: writeLinesSafe
- parameter: `output`, type: `java.io.OutputStream`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- return type: `boolean`

Description: Write UTF\-8 encoded strings. On error, the method returns false.
parameter: output: output stream
parameter: lines: lines to write
return: true on success

## Static Method: writeLinesSafe
- parameter: `file`, type: `java.io.File`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- parameter: `encoding`, type: `java.nio.charset.Charset`
- return type: `boolean`

Description: Write strings. On error, the method returns false.
parameter: file: output file
parameter: lines: lines to write
parameter: encoding: output encoding
return: true on success

## Static Method: writeLinesSafe
- parameter: `file`, type: `java.io.File`
- parameter: `lines`, type: `java.util.List<? extends java.lang.CharSequence>`
- return type: `boolean`

Description: Write UTF\-8 encoded strings. On error, the method returns false.
parameter: file: output file
parameter: lines: lines to write
return: true on success

## Static Method: writeTextFile
- parameter: `file`, type: `java.io.File`
- parameter: `str`, type: `java.lang.String`

Description: Write a string to a file using the default character encoding of the current system. Existing file contents will be overwritten.
parameter: file: destination file
parameter: str: string
throws: on error

## Static Method: writeTextFile
- parameter: `file`, type: `java.io.File`
- parameter: `str`, type: `java.lang.String`
- parameter: `encoding`, type: `java.nio.charset.Charset`

Description: Write a string to a file using the given character encoding of the current system. Existing file contents will be overwritten.
parameter: file: output file
parameter: str: string to write
parameter: charsetName: character set name
throws: if the file cannot be written