Package com.globalmentor.io

Class Filenames

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

  • Field Details

  • Method Details

    • isSpecialName

      public static boolean isSpecialName(@Nonnull String name)
      Determines if a filename is considered "special" (such as a parent directory designation) on file systems in general and cannot therefore be used as a normal filename.
      API Note:
      If this method returns true for a name, it does not necessarily mean that the name is considered special on every implementation of a FileSystem. See further discussion on Stack Overflow.
      Parameters:
      name - The filename to test.
      Returns:
      true if the given name is special and should not be used as a filename.
      See Also:

    • comparator

      public static Comparator<CharSequence> comparator()
      Returns a general filename comparator with neutral comparison across locales. A filename comparator sorts the base filename and extension separately.
      Implementation Specification:
      This implementation uses a collator that takes into account differences in case and accents.
      Returns:
      A neutral filename comparator for the root locale.
      See Also:

    • comparator

      public static Comparator<CharSequence> comparator(@Nonnull Locale locale)
      Returns a filename comparator for the given locale. A filename comparator sorts the base filename and extension separately.
      Implementation Specification:
      This implementation uses a collator that takes into account differences in case and accents.
      Parameters:
      locale - The locale to use for comparison.
      Returns:
      A filename comparator for the given locale.

    • comparator

      public static Comparator<CharSequence> comparator(@Nonnull Collator collator)
      Returns a filename comparator using the given collator. A filename comparator sorts the base filename and extension separately.
      Parameters:
      collator - The collator to use for comparisons.
      Returns:
      A filename comparator using the given collator.

    • isCrossPlatformFilename

      public static boolean isCrossPlatformFilename(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 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:
      IllegalArgumentException - if the filename is the empty string, which is not a valid filename.
      See Also:

    • isValidFilename

      public static boolean isValidFilename(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(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.

    • encodeCrossPlatformFilename

      public static String encodeCrossPlatformFilename(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.

      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.
      Returns:
      The string modified to be a filename.
      See Also:

    • encodeFilename

      public static String encodeFilename(String filename)
      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.

      The filename is encoded using the reserved characters of the current operating system.

      Parameters:
      filename - The filename string to be encoded.
      Returns:
      The string modified to be a filename.
      See Also:

    • encodeFilename

      public static String encodeFilename(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:

    • decodeFilename

      public static String decodeFilename(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:

    • getBaseFilenamePattern

      public static Pattern getBaseFilenamePattern(@Nonnull 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.

    • appendBase

      public static String appendBase(@Nonnull String filename, @Nonnull CharSequence charSequence)
      Appends a given string to the end of a filename before the extension, if any.
      API Note:
      This is useful for forming a locale-aware filename, such as test_fr.txt from test.txt., Here "base filename" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base filename of example.
      Parameters:
      filename - The filename that may contain an extension.
      charSequence - The characters to append to the filename.
      Returns:
      A filename with the given character sequence appended before the filename extension, if any.

    • appendBaseFilename

      @Deprecated public static String appendBaseFilename(String filename, CharSequence charSequence)
      Deprecated.
      to be removed in favor of appendBase(String, CharSequence).
      Appends a given string to the end of a filename before the extension, if any.
      API Note:
      This is useful for forming a locale-aware filename, such as test_fr.txt from test.txt., Here "base filename" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base filename of example.
      Parameters:
      filename - The filename that may contain an extension.
      charSequence - The characters to append to the filename.
      Returns:
      A filename with the given character sequence appended before the filename extension, if any.

    • changeBase

      public static String changeBase(@Nonnull String filename, @Nonnull String base)
      Changes the base filename, preserving the extension(s), if any.
      API Note:
      Here "base filename" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base filename of example.
      Parameters:
      filename - The filename to examine.
      base - The new base to set.
      Returns:
      The filename with the new base.
      Throws:
      NullPointerException - if the given filename and/or base is null.
      IllegalArgumentException - if the given filename and/or base is empty.

    • getBase

      public static String getBase(@Nonnull String filename)
      Retrieves a base filename with no extensions
      API Note:
      Here "base filename" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base filename of example.
      Parameters:
      filename - The filename that may contain an extension.
      Returns:
      A filename with all extensions, if any, removed.

    • getBaseFilename

      @Deprecated public static String getBaseFilename(String filename)
      Deprecated.
      to be removed in favor of getBase(String).
      Retrieves a base filename with no extensions
      API Note:
      Here "base filename" refers to the filename with all extensions removed. That is both example.bar and example.foo.bar would result in a base filename of example.
      Parameters:
      filename - The filename that may contain an extension.
      Returns:
      A filename with all extensions, if any, removed.

    • extensions

      public static Stream<String> extensions(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 Iterable<String> getExtensions(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:

    • addExtension

      public static String addExtension(String filename, 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.
      Implementation Note:
      This implementation currently allows an extension with the . delimiter, but it may be prohibited in the future., This implementation currently allows an empty filename, but 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:
      NullPointerException - if the given extension is null.

    • changeExtension

      public static String changeExtension(@Nonnull String filename, @Nullable 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:
      IllegalArgumentException - if the filename is empty.

    • findExtension

      public static Optional<String> findExtension(@Nonnull 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.

    • hasExtension

      public static boolean hasExtension(@Nonnull String filename, @Nonnull String extension)
      Determines whether a given filename has the indicated extension.

      This methods compares filenames on an ASCII case-insensitive basis. As such testing for the extension bar will return true both for the filename foo.bar and also for the filename foo.BAR.

      Implementation Specification:
      This implementation delegates to Filenames.Extensions.equals(String, String).
      Parameters:
      filename - The filename to check.
      extension - The extension to match.
      Returns:
      true if the given filename has the indicated extension in any allowed form.

    • getExtension

      @Deprecated public static String getExtension(@Nonnull String filename)
      Deprecated.
      to be removed in favor of findExtension(String).
      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 String removeExtension(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 String setExtension(String filename, 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.