FilenameUtils (Commons IO 2.5)
Date: 2016-12-01

org.apache.commons.io

## Class FilenameUtils

- java.lang.Object
- - org.apache.commons.io.FilenameUtils

-     public class FilenameUtils
      extends java.lang.Object

  General filename and filepath manipulation utilities.

  When dealing with filenames you can hit problems when moving from a Windows based development machine to a Unix based production machine. This class aims to help avoid those problems.

  NOTE: You may be able to avoid using this class entirely simply by using JDK `File` objects and the two argument constructor `File(File,String)`.

  Most methods on this class are designed to work the same on both Unix and Windows. Those that don't include 'System', 'Unix' or 'Windows' in their name.

  Most methods recognise both separators (forward and back), and both sets of prefixes. See the javadoc of each method for details.

  This class defines six components within a filename (example C:\dev\project\file.txt):

  - the prefix - C:\
  - the path - dev\project\
  - the full path - C:\dev\project\
  - the name - file.txt
  - the base name - file
  - the extension - txt
  Note that this class works best if directory filenames end with a separator. If you omit the last separator, it is impossible to determine if the filename corresponds to a file or a directory. As a result, we have chosen to say it corresponds to a file.

  This class only supports Unix and Windows style names. Prefixes are matched as follows:

       Windows:
       a\b\c.txt           --> ""          --> relative
       \a\b\c.txt          --> "\"         --> current drive absolute
       C:a\b\c.txt         --> "C:"        --> drive relative
       C:\a\b\c.txt        --> "C:\"       --> absolute
       \\server\a\b\c.txt  --> "\\server\" --> UNC

       Unix:
       a/b/c.txt           --> ""          --> relative
       /a/b/c.txt          --> "/"         --> absolute
       ~/a/b/c.txt         --> "~/"        --> current user
       ~                   --> "~/"        --> current user (slash added)
       ~user/a/b/c.txt     --> "~user/"    --> named user
       ~user               --> "~user/"    --> named user (slash added)

  Both prefix styles are matched always, irrespective of the machine that you are currently running on.

  Origin of code: Excalibur, Alexandria, Tomcat, Commons-Utils.

  Since:
    1.1
  Version:
    $Id: FilenameUtils.java 1702170 2015-09-10 06:35:02Z krosenvold $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static char` | `EXTENSION_SEPARATOR` The extension separator character.
    `static java.lang.String` | `EXTENSION_SEPARATOR_STR` The extension separator String.
    `private static int` | `NOT_FOUND`
    `private static char` | `OTHER_SEPARATOR` The separator character that is the opposite of the system separator.
    `private static char` | `SYSTEM_SEPARATOR` The system separator character.
    `private static char` | `UNIX_SEPARATOR` The Unix separator character.
    `private static char` | `WINDOWS_SEPARATOR` The Windows separator character.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FilenameUtils()` Instances should NOT be constructed in standard programming.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static java.lang.String` | `concat(java.lang.String basePath, java.lang.String fullFilenameToAdd)` Concatenates a filename to a base path using normal command line style rules.
    `static boolean` | `directoryContains(java.lang.String canonicalParent, java.lang.String canonicalChild)` Determines whether the `parent` directory contains the `child` element (a file or directory).
    `private static java.lang.String` | `doGetFullPath(java.lang.String filename, boolean includeSeparator)` Does the work of getting the path.
    `private static java.lang.String` | `doGetPath(java.lang.String filename, int separatorAdd)` Does the work of getting the path.
    `private static java.lang.String` | `doNormalize(java.lang.String filename, char separator, boolean keepSeparator)` Internal method to perform the normalization.
    `static boolean` | `equals(java.lang.String filename1, java.lang.String filename2)` Checks whether two filenames are equal exactly.
    `static boolean` | `equals(java.lang.String filename1, java.lang.String filename2, boolean normalized, IOCase caseSensitivity)` Checks whether two filenames are equal, optionally normalizing and providing control over the case-sensitivity.
    `static boolean` | `equalsNormalized(java.lang.String filename1, java.lang.String filename2)` Checks whether two filenames are equal after both have been normalized.
    `static boolean` | `equalsNormalizedOnSystem(java.lang.String filename1, java.lang.String filename2)` Checks whether two filenames are equal after both have been normalized and using the case rules of the system.
    `static boolean` | `equalsOnSystem(java.lang.String filename1, java.lang.String filename2)` Checks whether two filenames are equal using the case rules of the system.
    `private static void` | `failIfNullBytePresent(java.lang.String path)` Check the input for null bytes, a sign of unsanitized data being passed to to file level functions.
    `static java.lang.String` | `getBaseName(java.lang.String filename)` Gets the base name, minus the full path and extension, from a full filename.
    `static java.lang.String` | `getExtension(java.lang.String filename)` Gets the extension of a filename.
    `static java.lang.String` | `getFullPath(java.lang.String filename)` Gets the full path from a full filename, which is the prefix + path.
    `static java.lang.String` | `getFullPathNoEndSeparator(java.lang.String filename)` Gets the full path from a full filename, which is the prefix + path, and also excluding the final directory separator.
    `static java.lang.String` | `getName(java.lang.String filename)` Gets the name minus the path from a full filename.
    `static java.lang.String` | `getPath(java.lang.String filename)` Gets the path from a full filename, which excludes the prefix.
    `static java.lang.String` | `getPathNoEndSeparator(java.lang.String filename)` Gets the path from a full filename, which excludes the prefix, and also excluding the final directory separator.
    `static java.lang.String` | `getPrefix(java.lang.String filename)` Gets the prefix from a full filename, such as `C:/` or `~/`.
    `static int` | `getPrefixLength(java.lang.String filename)` Returns the length of the filename prefix, such as `C:/` or `~/`.
    `static int` | `indexOfExtension(java.lang.String filename)` Returns the index of the last extension separator character, which is a dot.
    `static int` | `indexOfLastSeparator(java.lang.String filename)` Returns the index of the last directory separator character.
    `static boolean` | `isExtension(java.lang.String filename, java.util.Collection<java.lang.String> extensions)` Checks whether the extension of the filename is one of those specified.
    `static boolean` | `isExtension(java.lang.String filename, java.lang.String extension)` Checks whether the extension of the filename is that specified.
    `static boolean` | `isExtension(java.lang.String filename, java.lang.String[] extensions)` Checks whether the extension of the filename is one of those specified.
    `private static boolean` | `isSeparator(char ch)` Checks if the character is a separator.
    `(package private) static boolean` | `isSystemWindows()` Determines if Windows file system is in use.
    `static java.lang.String` | `normalize(java.lang.String filename)` Normalizes a path, removing double and single dot path steps.
    `static java.lang.String` | `normalize(java.lang.String filename, boolean unixSeparator)` Normalizes a path, removing double and single dot path steps.
    `static java.lang.String` | `normalizeNoEndSeparator(java.lang.String filename)` Normalizes a path, removing double and single dot path steps, and removing any final directory separator.
    `static java.lang.String` | `normalizeNoEndSeparator(java.lang.String filename, boolean unixSeparator)` Normalizes a path, removing double and single dot path steps, and removing any final directory separator.
    `static java.lang.String` | `removeExtension(java.lang.String filename)` Removes the extension from a filename.
    `static java.lang.String` | `separatorsToSystem(java.lang.String path)` Converts all separators to the system separator.
    `static java.lang.String` | `separatorsToUnix(java.lang.String path)` Converts all separators to the Unix separator of forward slash.
    `static java.lang.String` | `separatorsToWindows(java.lang.String path)` Converts all separators to the Windows separator of backslash.
    `(package private) static java.lang.String[]` | `splitOnTokens(java.lang.String text)` Splits a string into a number of tokens.
    `static boolean` | `wildcardMatch(java.lang.String filename, java.lang.String wildcardMatcher)` Checks a filename to see if it matches the specified wildcard matcher, always testing case-sensitive.
    `static boolean` | `wildcardMatch(java.lang.String filename, java.lang.String wildcardMatcher, IOCase caseSensitivity)` Checks a filename to see if it matches the specified wildcard matcher allowing control over case-sensitivity.
    `static boolean` | `wildcardMatchOnSystem(java.lang.String filename, java.lang.String wildcardMatcher)` Checks a filename to see if it matches the specified wildcard matcher using the case rules of the system.

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

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

- - ### Field Detail

    - #### NOT_FOUND

          private static final int NOT_FOUND

      See Also:
        Constant Field Values

    - #### EXTENSION_SEPARATOR

          public static final char EXTENSION_SEPARATOR

      The extension separator character.
      Since:
        1.4
      See Also:
        Constant Field Values

    - #### EXTENSION_SEPARATOR_STR

          public static final java.lang.String EXTENSION_SEPARATOR_STR

      The extension separator String.
      Since:
        1.4

    - #### UNIX_SEPARATOR

          private static final char UNIX_SEPARATOR

      The Unix separator character.
      See Also:
        Constant Field Values

    - #### WINDOWS_SEPARATOR

          private static final char WINDOWS_SEPARATOR

      The Windows separator character.
      See Also:
        Constant Field Values

    - #### SYSTEM_SEPARATOR

          private static final char SYSTEM_SEPARATOR

      The system separator character.

    - #### OTHER_SEPARATOR

          private static final char OTHER_SEPARATOR

      The separator character that is the opposite of the system separator.

  - ### Constructor Detail

    - #### FilenameUtils

          public FilenameUtils()

      Instances should NOT be constructed in standard programming.

  - ### Method Detail

    - #### isSystemWindows

          static boolean isSystemWindows()

      Determines if Windows file system is in use.
      Returns:
        true if the system is Windows

    - #### isSeparator

          private static boolean isSeparator(char ch)

      Checks if the character is a separator.
      Parameters:
        `ch` - the character to check
      Returns:
        true if it is a separator character

    - #### normalize

          public static java.lang.String normalize(java.lang.String filename)

      Normalizes a path, removing double and single dot path steps.

      This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format of the system.

      A trailing slash will be retained. A double slash will be merged to a single slash (but UNC names are handled). A single dot path segment will be removed. A double dot will cause that path segment and the one before to be removed. If the double dot has no parent path segment to work with, `null` is returned.

      The output will be the same on both Unix and Windows except for the separator character.

           /foo//               -->   /foo/
           /foo/./              -->   /foo/
           /foo/../bar          -->   /bar
           /foo/../bar/         -->   /bar/
           /foo/../bar/../baz   -->   /baz
           //foo//./bar         -->   /foo/bar
           /../                 -->   null
           ../foo               -->   null
           foo/bar/..           -->   foo/
           foo/../../bar        -->   null
           foo/../bar           -->   bar
           //server/foo/../bar  -->   //server/bar
           //server/../bar      -->   null
           C:\foo\..\bar        -->   C:\bar
           C:\..\bar            -->   null
           ~/foo/../bar/        -->   ~/bar/
           ~/../bar             -->   null

      (Note the file separator returned will be correct for Windows/Unix)
      Parameters:
        `filename` - the filename to normalize, null returns null
      Returns:
        the normalized filename, or null if invalid. Null bytes inside string will be removed

    - #### normalize

          public static java.lang.String normalize(java.lang.String filename,
                                   boolean unixSeparator)

      Normalizes a path, removing double and single dot path steps.

      This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format specified.

      A trailing slash will be retained. A double slash will be merged to a single slash (but UNC names are handled). A single dot path segment will be removed. A double dot will cause that path segment and the one before to be removed. If the double dot has no parent path segment to work with, `null` is returned.

      The output will be the same on both Unix and Windows except for the separator character.

           /foo//               -->   /foo/
           /foo/./              -->   /foo/
           /foo/../bar          -->   /bar
           /foo/../bar/         -->   /bar/
           /foo/../bar/../baz   -->   /baz
           //foo//./bar         -->   /foo/bar
           /../                 -->   null
           ../foo               -->   null
           foo/bar/..           -->   foo/
           foo/../../bar        -->   null
           foo/../bar           -->   bar
           //server/foo/../bar  -->   //server/bar
           //server/../bar      -->   null
           C:\foo\..\bar        -->   C:\bar
           C:\..\bar            -->   null
           ~/foo/../bar/        -->   ~/bar/
           ~/../bar             -->   null

      The output will be the same on both Unix and Windows including the separator character.
      Parameters:
        `filename` - the filename to normalize, null returns null
        `unixSeparator` - `true` if a unix separator should be used or `false` if a windows separator should be used.
      Returns:
        the normalized filename, or null if invalid. Null bytes inside string will be removed
      Since:
        2.0

    - #### normalizeNoEndSeparator

          public static java.lang.String normalizeNoEndSeparator(java.lang.String filename)

      Normalizes a path, removing double and single dot path steps, and removing any final directory separator.

      This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format of the system.

      A trailing slash will be removed. A double slash will be merged to a single slash (but UNC names are handled). A single dot path segment will be removed. A double dot will cause that path segment and the one before to be removed. If the double dot has no parent path segment to work with, `null` is returned.

      The output will be the same on both Unix and Windows except for the separator character.

           /foo//               -->   /foo
           /foo/./              -->   /foo
           /foo/../bar          -->   /bar
           /foo/../bar/         -->   /bar
           /foo/../bar/../baz   -->   /baz
           //foo//./bar         -->   /foo/bar
           /../                 -->   null
           ../foo               -->   null
           foo/bar/..           -->   foo
           foo/../../bar        -->   null
           foo/../bar           -->   bar
           //server/foo/../bar  -->   //server/bar
           //server/../bar      -->   null
           C:\foo\..\bar        -->   C:\bar
           C:\..\bar            -->   null
           ~/foo/../bar/        -->   ~/bar
           ~/../bar             -->   null

      (Note the file separator returned will be correct for Windows/Unix)
      Parameters:
        `filename` - the filename to normalize, null returns null
      Returns:
        the normalized filename, or null if invalid. Null bytes inside string will be removed

    - #### normalizeNoEndSeparator

          public static java.lang.String normalizeNoEndSeparator(java.lang.String filename,
                                                 boolean unixSeparator)

      Normalizes a path, removing double and single dot path steps, and removing any final directory separator.

      This method normalizes a path to a standard format. The input may contain separators in either Unix or Windows format. The output will contain separators in the format specified.

      A trailing slash will be removed. A double slash will be merged to a single slash (but UNC names are handled). A single dot path segment will be removed. A double dot will cause that path segment and the one before to be removed. If the double dot has no parent path segment to work with, `null` is returned.

      The output will be the same on both Unix and Windows including the separator character.

           /foo//               -->   /foo
           /foo/./              -->   /foo
           /foo/../bar          -->   /bar
           /foo/../bar/         -->   /bar
           /foo/../bar/../baz   -->   /baz
           //foo//./bar         -->   /foo/bar
           /../                 -->   null
           ../foo               -->   null
           foo/bar/..           -->   foo
           foo/../../bar        -->   null
           foo/../bar           -->   bar
           //server/foo/../bar  -->   //server/bar
           //server/../bar      -->   null
           C:\foo\..\bar        -->   C:\bar
           C:\..\bar            -->   null
           ~/foo/../bar/        -->   ~/bar
           ~/../bar             -->   null

      Parameters:
        `filename` - the filename to normalize, null returns null
        `unixSeparator` - `true` if a unix separator should be used or `false` if a windows separtor should be used.
      Returns:
        the normalized filename, or null if invalid. Null bytes inside string will be removed
      Since:
        2.0

    - #### doNormalize

          private static java.lang.String doNormalize(java.lang.String filename,
                                     char separator,
                                     boolean keepSeparator)

      Internal method to perform the normalization.
      Parameters:
        `filename` - the filename
        `separator` - The separator character to use
        `keepSeparator` - true to keep the final separator
      Returns:
        the normalized filename. Null bytes inside string will be removed.

    - #### concat

          public static java.lang.String concat(java.lang.String basePath,
                                java.lang.String fullFilenameToAdd)

      Concatenates a filename to a base path using normal command line style rules.

      The effect is equivalent to resultant directory after changing directory to the first argument, followed by changing directory to the second argument.

      The first argument is the base path, the second is the path to concatenate. The returned path is always normalized via `normalize(String)`, thus `..` is handled.

      If `pathToAdd` is absolute (has an absolute prefix), then it will be normalized and returned. Otherwise, the paths will be joined, normalized and returned.

      The output will be the same on both Unix and Windows except for the separator character.

           /foo/ + bar          -->   /foo/bar
           /foo + bar           -->   /foo/bar
           /foo + /bar          -->   /bar
           /foo + C:/bar        -->   C:/bar
           /foo + C:bar         -->   C:bar (*)
           /foo/a/ + ../bar     -->   foo/bar
           /foo/ + ../../bar    -->   null
           /foo/ + /bar         -->   /bar
           /foo/.. + /bar       -->   /bar
           /foo + bar/c.txt     -->   /foo/bar/c.txt
           /foo/c.txt + bar     -->   /foo/c.txt/bar (!)

      (*) Note that the Windows relative drive prefix is unreliable when used with this method. (!) Note that the first parameter must be a path. If it ends with a name, then the name will be built into the concatenated path. If this might be a problem, use `getFullPath(String)` on the base path argument.
      Parameters:
        `basePath` - the base path to attach to, always treated as a path
        `fullFilenameToAdd` - the filename (or path) to attach to the base
      Returns:
        the concatenated path, or null if invalid. Null bytes inside string will be removed

    - #### directoryContains

          public static boolean directoryContains(java.lang.String canonicalParent,
                                  java.lang.String canonicalChild)
                                           throws java.io.IOException

      Determines whether the `parent` directory contains the `child` element (a file or directory).

      The files names are expected to be normalized.

      Edge cases:
      - A `directory` must not be null: if null, throw IllegalArgumentException
      - A directory does not contain itself: return false
      - A null child file is not contained in any parent: return false
      Parameters:
        `canonicalParent` - the file to consider as the parent.
        `canonicalChild` - the file to consider as the child.
      Returns:
        true is the candidate leaf is under by the specified composite. False otherwise.
      Throws:
        `java.io.IOException` - if an IO error occurs while checking the files.
      Since:
        2.2
      See Also:
        `FileUtils.directoryContains(File, File)`

    - #### separatorsToUnix

          public static java.lang.String separatorsToUnix(java.lang.String path)

      Converts all separators to the Unix separator of forward slash.
      Parameters:
        `path` - the path to be changed, null ignored
      Returns:
        the updated path

    - #### separatorsToWindows

          public static java.lang.String separatorsToWindows(java.lang.String path)

      Converts all separators to the Windows separator of backslash.
      Parameters:
        `path` - the path to be changed, null ignored
      Returns:
        the updated path

    - #### separatorsToSystem

          public static java.lang.String separatorsToSystem(java.lang.String path)

      Converts all separators to the system separator.
      Parameters:
        `path` - the path to be changed, null ignored
      Returns:
        the updated path

    - #### getPrefixLength

          public static int getPrefixLength(java.lang.String filename)

      Returns the length of the filename prefix, such as `C:/` or `~/`.

      This method will handle a file in either Unix or Windows format.

      The prefix length includes the first slash in the full filename if applicable. Thus, it is possible that the length returned is greater than the length of the input string.

           Windows:
           a\b\c.txt           --> ""          --> relative
           \a\b\c.txt          --> "\"         --> current drive absolute
           C:a\b\c.txt         --> "C:"        --> drive relative
           C:\a\b\c.txt        --> "C:\"       --> absolute
           \\server\a\b\c.txt  --> "\\server\" --> UNC
           \\\a\b\c.txt        -->  error, length = -1

           Unix:
           a/b/c.txt           --> ""          --> relative
           /a/b/c.txt          --> "/"         --> absolute
           ~/a/b/c.txt         --> "~/"        --> current user
           ~                   --> "~/"        --> current user (slash added)
           ~user/a/b/c.txt     --> "~user/"    --> named user
           ~user               --> "~user/"    --> named user (slash added)
           //server/a/b/c.txt  --> "//server/"
           ///a/b/c.txt        --> error, length = -1

      The output will be the same irrespective of the machine that the code is running on. ie. both Unix and Windows prefixes are matched regardless. Note that a leading // (or \\) is used to indicate a UNC name on Windows. These must be followed by a server name, so double-slashes are not collapsed to a single slash at the start of the filename.

      Parameters:
        `filename` - the filename to find the prefix in, null returns -1
      Returns:
        the length of the prefix, -1 if invalid or null

    - #### indexOfLastSeparator

          public static int indexOfLastSeparator(java.lang.String filename)

      Returns the index of the last directory separator character.

      This method will handle a file in either Unix or Windows format. The position of the last forward or backslash is returned.

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to find the last path separator in, null returns -1
      Returns:
        the index of the last separator character, or -1 if there is no such character

    - #### indexOfExtension

          public static int indexOfExtension(java.lang.String filename)

      Returns the index of the last extension separator character, which is a dot.

      This method also checks that there is no directory separator after the last dot. To do this it uses `indexOfLastSeparator(String)` which will handle a file in either Unix or Windows format.

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to find the last extension separator in, null returns -1
      Returns:
        the index of the last extension separator character, or -1 if there is no such character

    - #### getPrefix

          public static java.lang.String getPrefix(java.lang.String filename)

      Gets the prefix from a full filename, such as `C:/` or `~/`.

      This method will handle a file in either Unix or Windows format. The prefix includes the first slash in the full filename where applicable.

           Windows:
           a\b\c.txt           --> ""          --> relative
           \a\b\c.txt          --> "\"         --> current drive absolute
           C:a\b\c.txt         --> "C:"        --> drive relative
           C:\a\b\c.txt        --> "C:\"       --> absolute
           \\server\a\b\c.txt  --> "\\server\" --> UNC

           Unix:
           a/b/c.txt           --> ""          --> relative
           /a/b/c.txt          --> "/"         --> absolute
           ~/a/b/c.txt         --> "~/"        --> current user
           ~                   --> "~/"        --> current user (slash added)
           ~user/a/b/c.txt     --> "~user/"    --> named user
           ~user               --> "~user/"    --> named user (slash added)

      The output will be the same irrespective of the machine that the code is running on. ie. both Unix and Windows prefixes are matched regardless.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the prefix of the file, null if invalid. Null bytes inside string will be removed

    - #### getPath

          public static java.lang.String getPath(java.lang.String filename)

      Gets the path from a full filename, which excludes the prefix.

      This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before and including the last forward or backslash.

           C:\a\b\c.txt --> a\b\
           ~/a/b/c.txt  --> a/b/
           a.txt        --> ""
           a/b/c        --> a/b/
           a/b/c/       --> a/b/c/

      The output will be the same irrespective of the machine that the code is running on.

      This method drops the prefix from the result. See `getFullPath(String)` for the method that retains the prefix.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the path of the file, an empty string if none exists, null if invalid. Null bytes inside string will be removed

    - #### getPathNoEndSeparator

          public static java.lang.String getPathNoEndSeparator(java.lang.String filename)

      Gets the path from a full filename, which excludes the prefix, and also excluding the final directory separator.

      This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before the last forward or backslash.

           C:\a\b\c.txt --> a\b
           ~/a/b/c.txt  --> a/b
           a.txt        --> ""
           a/b/c        --> a/b
           a/b/c/       --> a/b/c

      The output will be the same irrespective of the machine that the code is running on.

      This method drops the prefix from the result. See `getFullPathNoEndSeparator(String)` for the method that retains the prefix.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the path of the file, an empty string if none exists, null if invalid. Null bytes inside string will be removed

    - #### doGetPath

          private static java.lang.String doGetPath(java.lang.String filename,
                                   int separatorAdd)

      Does the work of getting the path.
      Parameters:
        `filename` - the filename
        `separatorAdd` - 0 to omit the end separator, 1 to return it
      Returns:
        the path. Null bytes inside string will be removed

    - #### getFullPath

          public static java.lang.String getFullPath(java.lang.String filename)

      Gets the full path from a full filename, which is the prefix + path.

      This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before and including the last forward or backslash.

           C:\a\b\c.txt --> C:\a\b\
           ~/a/b/c.txt  --> ~/a/b/
           a.txt        --> ""
           a/b/c        --> a/b/
           a/b/c/       --> a/b/c/
           C:           --> C:
           C:\          --> C:\
           ~            --> ~/
           ~/           --> ~/
           ~user        --> ~user/
           ~user/       --> ~user/

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the path of the file, an empty string if none exists, null if invalid

    - #### getFullPathNoEndSeparator

          public static java.lang.String getFullPathNoEndSeparator(java.lang.String filename)

      Gets the full path from a full filename, which is the prefix + path, and also excluding the final directory separator.

      This method will handle a file in either Unix or Windows format. The method is entirely text based, and returns the text before the last forward or backslash.

           C:\a\b\c.txt --> C:\a\b
           ~/a/b/c.txt  --> ~/a/b
           a.txt        --> ""
           a/b/c        --> a/b
           a/b/c/       --> a/b/c
           C:           --> C:
           C:\          --> C:\
           ~            --> ~
           ~/           --> ~
           ~user        --> ~user
           ~user/       --> ~user

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the path of the file, an empty string if none exists, null if invalid

    - #### doGetFullPath

          private static java.lang.String doGetFullPath(java.lang.String filename,
                                       boolean includeSeparator)

      Does the work of getting the path.
      Parameters:
        `filename` - the filename
        `includeSeparator` - true to include the end separator
      Returns:
        the path

    - #### getName

          public static java.lang.String getName(java.lang.String filename)

      Gets the name minus the path from a full filename.

      This method will handle a file in either Unix or Windows format. The text after the last forward or backslash is returned.

           a/b/c.txt --> c.txt
           a.txt     --> a.txt
           a/b/c     --> c
           a/b/c/    --> ""

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the name of the file without the path, or an empty string if none exists. Null bytes inside string will be removed

    - #### failIfNullBytePresent

          private static void failIfNullBytePresent(java.lang.String path)

      Check the input for null bytes, a sign of unsanitized data being passed to to file level functions. This may be used for poison byte attacks.
      Parameters:
        `path` - the path to check

    - #### getBaseName

          public static java.lang.String getBaseName(java.lang.String filename)

      Gets the base name, minus the full path and extension, from a full filename.

      This method will handle a file in either Unix or Windows format. The text after the last forward or backslash and before the last dot is returned.

           a/b/c.txt --> c
           a.txt     --> a
           a/b/c     --> c
           a/b/c/    --> ""

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the name of the file without the path, or an empty string if none exists. Null bytes inside string will be removed

    - #### getExtension

          public static java.lang.String getExtension(java.lang.String filename)

      Gets the extension of a filename.

      This method returns the textual part of the filename after the last dot. There must be no directory separator after the dot.

           foo.txt      --> "txt"
           a/b/c.jpg    --> "jpg"
           a/b.txt/c    --> ""
           a/b/c        --> ""

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to retrieve the extension of.
      Returns:
        the extension of the file or an empty string if none exists or `null` if the filename is `null`.

    - #### removeExtension

          public static java.lang.String removeExtension(java.lang.String filename)

      Removes the extension from a filename.

      This method returns the textual part of the filename before the last dot. There must be no directory separator after the dot.

           foo.txt    --> foo
           a\b\c.jpg  --> a\b\c
           a\b\c      --> a\b\c
           a.b\c      --> a.b\c

      The output will be the same irrespective of the machine that the code is running on.

      Parameters:
        `filename` - the filename to query, null returns null
      Returns:
        the filename minus the extension

    - #### equals

          public static boolean equals(java.lang.String filename1,
                       java.lang.String filename2)

      Checks whether two filenames are equal exactly.

      No processing is performed on the filenames other than comparison, thus this is merely a null-safe case-sensitive equals.

      Parameters:
        `filename1` - the first filename to query, may be null
        `filename2` - the second filename to query, may be null
      Returns:
        true if the filenames are equal, null equals null
      See Also:
        `IOCase.SENSITIVE`

    - #### equalsOnSystem

          public static boolean equalsOnSystem(java.lang.String filename1,
                               java.lang.String filename2)

      Checks whether two filenames are equal using the case rules of the system.

      No processing is performed on the filenames other than comparison. The check is case-sensitive on Unix and case-insensitive on Windows.

      Parameters:
        `filename1` - the first filename to query, may be null
        `filename2` - the second filename to query, may be null
      Returns:
        true if the filenames are equal, null equals null
      See Also:
        `IOCase.SYSTEM`

    - #### equalsNormalized

          public static boolean equalsNormalized(java.lang.String filename1,
                                 java.lang.String filename2)

      Checks whether two filenames are equal after both have been normalized.

      Both filenames are first passed to `normalize(String)`. The check is then performed in a case-sensitive manner.

      Parameters:
        `filename1` - the first filename to query, may be null
        `filename2` - the second filename to query, may be null
      Returns:
        true if the filenames are equal, null equals null
      See Also:
        `IOCase.SENSITIVE`

    - #### equalsNormalizedOnSystem

          public static boolean equalsNormalizedOnSystem(java.lang.String filename1,
                                         java.lang.String filename2)

      Checks whether two filenames are equal after both have been normalized and using the case rules of the system.

      Both filenames are first passed to `normalize(String)`. The check is then performed case-sensitive on Unix and case-insensitive on Windows.

      Parameters:
        `filename1` - the first filename to query, may be null
        `filename2` - the second filename to query, may be null
      Returns:
        true if the filenames are equal, null equals null
      See Also:
        `IOCase.SYSTEM`

    - #### equals

          public static boolean equals(java.lang.String filename1,
                       java.lang.String filename2,
                       boolean normalized,
                       IOCase caseSensitivity)

      Checks whether two filenames are equal, optionally normalizing and providing control over the case-sensitivity.
      Parameters:
        `filename1` - the first filename to query, may be null
        `filename2` - the second filename to query, may be null
        `normalized` - whether to normalize the filenames
        `caseSensitivity` - what case sensitivity rule to use, null means case-sensitive
      Returns:
        true if the filenames are equal, null equals null
      Since:
        1.3

    - #### isExtension

          public static boolean isExtension(java.lang.String filename,
                            java.lang.String extension)

      Checks whether the extension of the filename is that specified.

      This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.

      Parameters:
        `filename` - the filename to query, null returns false
        `extension` - the extension to check for, null or empty checks for no extension
      Returns:
        true if the filename has the specified extension
      Throws:
        `java.lang.IllegalArgumentException` - if the supplied filename contains null bytes

    - #### isExtension

          public static boolean isExtension(java.lang.String filename,
                            java.lang.String[] extensions)

      Checks whether the extension of the filename is one of those specified.

      This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.

      Parameters:
        `filename` - the filename to query, null returns false
        `extensions` - the extensions to check for, null checks for no extension
      Returns:
        true if the filename is one of the extensions
      Throws:
        `java.lang.IllegalArgumentException` - if the supplied filename contains null bytes

    - #### isExtension

          public static boolean isExtension(java.lang.String filename,
                            java.util.Collection<java.lang.String> extensions)

      Checks whether the extension of the filename is one of those specified.

      This method obtains the extension as the textual part of the filename after the last dot. There must be no directory separator after the dot. The extension check is case-sensitive on all platforms.

      Parameters:
        `filename` - the filename to query, null returns false
        `extensions` - the extensions to check for, null checks for no extension
      Returns:
        true if the filename is one of the extensions
      Throws:
        `java.lang.IllegalArgumentException` - if the supplied filename contains null bytes

    - #### wildcardMatch

          public static boolean wildcardMatch(java.lang.String filename,
                              java.lang.String wildcardMatcher)

      Checks a filename to see if it matches the specified wildcard matcher, always testing case-sensitive.

      The wildcard matcher uses the characters '?' and '*' to represent a single or multiple (zero or more) wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-sensitive always.

           wildcardMatch("c.txt", "*.txt")      --> true
           wildcardMatch("c.txt", "*.jpg")      --> false
           wildcardMatch("a/b/c.txt", "a/b/*")  --> true
           wildcardMatch("c.txt", "*.???")      --> true
           wildcardMatch("c.txt", "*.????")     --> false

      N.B. the sequence "*?" does not work properly at present in match strings.
      Parameters:
        `filename` - the filename to match on
        `wildcardMatcher` - the wildcard string to match against
      Returns:
        true if the filename matches the wilcard string
      See Also:
        `IOCase.SENSITIVE`

    - #### wildcardMatchOnSystem

          public static boolean wildcardMatchOnSystem(java.lang.String filename,
                                      java.lang.String wildcardMatcher)

      Checks a filename to see if it matches the specified wildcard matcher using the case rules of the system.

      The wildcard matcher uses the characters '?' and '*' to represent a single or multiple (zero or more) wildcard characters. This is the same as often found on Dos/Unix command lines. The check is case-sensitive on Unix and case-insensitive on Windows.

           wildcardMatch("c.txt", "*.txt")      --> true
           wildcardMatch("c.txt", "*.jpg")      --> false
           wildcardMatch("a/b/c.txt", "a/b/*")  --> true
           wildcardMatch("c.txt", "*.???")      --> true
           wildcardMatch("c.txt", "*.????")     --> false

      N.B. the sequence "*?" does not work properly at present in match strings.
      Parameters:
        `filename` - the filename to match on
        `wildcardMatcher` - the wildcard string to match against
      Returns:
        true if the filename matches the wilcard string
      See Also:
        `IOCase.SYSTEM`

    - #### wildcardMatch

          public static boolean wildcardMatch(java.lang.String filename,
                              java.lang.String wildcardMatcher,
                              IOCase caseSensitivity)

      Checks a filename to see if it matches the specified wildcard matcher allowing control over case-sensitivity.

      The wildcard matcher uses the characters '?' and '*' to represent a single or multiple (zero or more) wildcard characters. N.B. the sequence "*?" does not work properly at present in match strings.

      Parameters:
        `filename` - the filename to match on
        `wildcardMatcher` - the wildcard string to match against
        `caseSensitivity` - what case sensitivity rule to use, null means case-sensitive
      Returns:
        true if the filename matches the wilcard string
      Since:
        1.3

    - #### splitOnTokens

          static java.lang.String[] splitOnTokens(java.lang.String text)

      Splits a string into a number of tokens. The text is split by '?' and '*'. Where multiple '*' occur consecutively they are collapsed into a single '*'.
      Parameters:
        `text` - the text to split
      Returns:
        the array of tokens, never null

Copyright (c) 2002-2016 Apache Software Foundation