Package com.globalmentor.io

Class Filenames

  • public class Filenames
extends java.lang.Object
    Utilities for working with filenames, whether from files, paths, or URIs for example.
    Author:
    Garret Wilson

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String addExtension​(java.lang.String filename, java.lang.String extension)
      Adds the given extension to a filename and returns the new filename with the new extension.
      static java.lang.String appendBaseFilename​(java.lang.String filename, java.lang.CharSequence charSequence)
      Appends a given string to the end of a filename before the extension, if any.
      static java.lang.String changeExtension​(java.lang.String filename, java.lang.String extension)
      Changes the last extension of a filename and returns a new filename with the new extension.
      static java.lang.String decodeFilename​(java.lang.String filename)
      Unescapes all characters in a string that are encoded using '^' as an escape character followed by two hex digits.
      static java.lang.String encodeCrossPlatformFilename​(java.lang.String filename)
      Escape all reserved filename characters to a two-digit uppercase hex representation using '^' as an escape character so that the filename can be used across operating systems.
      static java.lang.String encodeFilename​(java.lang.String filename)
      Escape all reserved filename characters to a two-digit uppercase hex representation using '^' as an escape character.
      static java.lang.String encodeFilename​(java.lang.String filename, Characters reservedCharacters, Characters reservedFinalCharacters)
      Escape all reserved filename characters to a two-digit uppercase hex representation using '^' as an escape character.
      static java.util.stream.Stream<java.lang.String> extensions​(java.lang.CharSequence filename)
      Returns all the possible extensions of a filename, from the most specific to the most general.
      static java.lang.String getBaseFilename​(java.lang.String filename)
      Retrieves a base filename with no extensions
      static java.util.regex.Pattern getBaseFilenamePattern​(java.lang.String baseFilename)
      Creates a pattern for matching a base filename (the given base name followed by one or more filename extensions).
      static java.lang.String getExtension​(java.lang.String filename)
      Extracts the extension from a filename.
      static java.lang.Iterable<java.lang.String> getExtensions​(java.lang.CharSequence filename)
      Returns all the possible extensions of a filename, from the most specific to the most general.
      static boolean isCrossPlatformFilename​(java.lang.String string)
      Checks to ensure that a particular string is a valid filename across operating systems.
      static boolean isDotfileFilename​(java.lang.CharSequence filename)
      Determines whether the filename is for a so-called "dotfile", beginning with a dot but including at least one other character.
      static boolean isValidFilename​(java.lang.String string)
      Checks to ensure that a particular string is a valid filename for the operating system.
      static boolean isValidFilename​(java.lang.String string, Characters reservedCharacters, Characters reservedFinalCharacters)
      Checks to ensure that a particular string is a valid filename.
      static java.lang.String removeExtension​(java.lang.String filename)
      Removes the last extension, if any, of a filename and returns a new filename with no extension.
      static java.lang.String setExtension​(java.lang.String filename, java.lang.String extension)
      Adds the extension, if any, to a filename and returns the new filename.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • getBaseFilenamePattern

        public static java.util.regex.Pattern getBaseFilenamePattern​(@Nonnull
                                                             java.lang.String baseFilename)
        Creates a pattern for matching a base filename (the given base name followed by one or more filename extensions).
        Parameters:
        baseFilename - The filename base name to match.
        Returns:
        A pattern for for matching filenames against the given base name.

      • appendBaseFilename

        public static java.lang.String appendBaseFilename​(java.lang.String filename,
                                                  java.lang.CharSequence charSequence)
        Appends a given string to the end of a filename before the extension, if any. This is useful for forming a locale-aware filename, such as test_fr.txt from test.txt.
        Parameters:
        filename - The filename that may contain an extension.
        charSequence - The characters to append to the filename.
        Returns:
        A filename with the given string appended before the filename extension, if any.

      • getBaseFilename

        public static java.lang.String getBaseFilename​(java.lang.String filename)
        Retrieves a base filename with no extensions
        Parameters:
        filename - The filename that may contain an extension.
        Returns:
        A filename with all extensions, if any, removed.

      • isCrossPlatformFilename

        public static boolean isCrossPlatformFilename​(java.lang.String string)
        Checks to ensure that a particular string is a valid filename across operating systems.
        Parameters:
        string - The string of characters which may represent a filename.
        Returns:
        true if the string contains no illegal filename characters.

      • isDotfileFilename

        public static boolean isDotfileFilename​(@Nonnull
                                        java.lang.CharSequence filename)
        Determines whether the filename is for a so-called "dotfile", beginning with a dot but including at least one other character. This method does not consider "." and ".." to be dotfile filenames.
        Implementation Specification:
        The current implementation currently does not consider whether the filename contains slashes of any sort, assuming that the string is actually a filename if it is non-empty.
        Parameters:
        filename - The filename to check.
        Returns:
        true if the filename is considered a dotfile.
        Throws:
        java.lang.IllegalArgumentException - if the filename is the empty string, which is not a valid filename.
        See Also:
        Why do some file/folder names on Windows have a dot in front of them?, Dotfiles, DOTFILE_PREFIX

      • isValidFilename

        public static boolean isValidFilename​(java.lang.String string)
        Checks to ensure that a particular string is a valid filename for the operating system.

        The reserved characters of the current operating system will be used.

        Parameters:
        string - The string of characters which may represent a filename.
        Returns:
        true if the string contains no illegal filename characters.

      • isValidFilename

        public static boolean isValidFilename​(java.lang.String string,
                                      Characters reservedCharacters,
                                      Characters reservedFinalCharacters)
        Checks to ensure that a particular string is a valid filename.
        Parameters:
        string - The string of characters which may represent a filename.
        reservedCharacters - The reserved characters which should be encoded.
        reservedFinalCharacters - The characters that should be encoded if they appear in the final position of the filename, or null if the final character doesn't have to meet special rules.
        Returns:
        true if the string contains no reserved filename characters.

      • encodeFilename

        public static java.lang.String encodeFilename​(java.lang.String filename,
                                              Characters reservedCharacters,
                                              Characters reservedFinalCharacters)
        Escape all reserved filename characters to a two-digit uppercase hex representation using '^' as an escape character.

        Note that this encodes path separators, and therefore this method should only be called on filenames, not paths.

        Parameters:
        filename - The filename string to be encoded.
        reservedCharacters - The reserved characters which should be encoded.
        reservedFinalCharacters - The characters that should be encoded if they appear in the final position of the filename, or null if the final character doesn't have to meet special rules.
        Returns:
        The string modified to be a filename.
        See Also:
        ESCAPE_CHAR, CharSequences.escapeHex(CharSequence, Characters, Characters, int, char, int, Case), isValidFilename(String, Characters, Characters)

      • decodeFilename

        public static java.lang.String decodeFilename​(java.lang.String filename)
        Unescapes all characters in a string that are encoded using '^' as an escape character followed by two hex digits.
        Parameters:
        filename - The filename string to be decoded.
        Returns:
        The filename string decoded back to a normal string.
        See Also:
        ESCAPE_CHAR, CharSequences.unescapeHex(CharSequence, char, int)

      • extensions

        public static java.util.stream.Stream<java.lang.String> extensions​(java.lang.CharSequence filename)
        Returns all the possible extensions of a filename, from the most specific to the most general.

        For example for the filename example.foo.bar the following would be returned in order:

        1. foo.bar
        2. bar
        Parameters:
        filename - The filename for which extensions should be returned.
        Returns:
        A stream of extensions of the given filename.

      • getExtensions

        public static java.lang.Iterable<java.lang.String> getExtensions​(java.lang.CharSequence filename)
        Returns all the possible extensions of a filename, from the most specific to the most general.

        For example for the filename example.foo.bar the following would be returned in order:

        1. foo.bar
        2. bar
        Parameters:
        filename - The filename for which extensions should be returned.
        Returns:
        An iterable to iterate over the extensions of the given filename.
        See Also:
        FilenameExtensionIterator

      • addExtension

        public static java.lang.String addExtension​(java.lang.String filename,
                                            java.lang.String extension)
        Adds the given extension to a filename and returns the new filename with the new extension. The name is not checked to see if it currently has an extension.

        This method currently allows an extension with the . delimiter, but it may be prohibited in the future.

        Parameters:
        filename - The filename name to which to add an extension.
        extension - The extension to add.
        Returns:
        The name with the new extension.
        Throws:
        java.lang.NullPointerException - if the given extension is null.

      • changeExtension

        public static java.lang.String changeExtension​(java.lang.String filename,
                                               java.lang.String extension)
        Changes the last extension of a filename and returns a new filename with the new extension. If the filename does not currently have an extension, one will be added.
        Parameters:
        filename - The filename to examine.
        extension - The extension to set, or null if the extension should be removed.
        Returns:
        The filename with the new extension.
        Throws:
        java.lang.IllegalArgumentException - If the name is empty, or if the name is just a "/".

      • getExtension

        public static java.lang.String getExtension​(java.lang.String filename)
        Extracts the extension from a filename.
        Parameters:
        filename - The filename to examine.
        Returns:
        The extension of the name (not including '.'), which may not be present.

      • removeExtension

        public static java.lang.String removeExtension​(java.lang.String filename)
        Removes the last extension, if any, of a filename and returns a new filename with no extension. This is a convenience method that delegates to changeExtension(String, String).
        Parameters:
        filename - The name to examine.
        Returns:
        The name with no extension.

      • setExtension

        public static java.lang.String setExtension​(java.lang.String filename,
                                            java.lang.String extension)
        Adds the extension, if any, to a filename and returns the new filename. This is a convenience method that delegates to addExtension(String, String) if a non-null extension is given.
        Parameters:
        filename - The filename to examine.
        extension - The extension to add, or null if no extension should be added.
        Returns:
        The name with the new extension, if any.