Package com.globalmentor.io

Class Paths

java.lang.Object

com.globalmentor.io.Paths

public class Paths
extends Object

Utility methods to manipulate Paths.

Author:

Magno Nascimento, Garret Wilson

Method Summary

Modifier and Type	Method	Description
static Path	addExtension(Path path, String extension)	Deprecated. to be removed in favor of addFilenameExtension(Path, String).
static Path	addFilenameExtension(Path path, String extension)	Adds the given extension to a path and returns the new path with the new extension.
static Path	appendFilenameBase(Path path, CharSequence charSequence)	Appends a given string to the end of the path's filename before the extension, if any.
static Predicate<Path>	byBaseFilename(String baseFilename)	Returns a predicate for matching paths by a base filename.
static Predicate<Path>	byFilenamePattern(Pattern filenamePattern)	Returns a predicate for a given filename pattern.
static Path	changeBase(Path path, Path oldBasePath, Path newBasePath)	Changes a path from one base to another.
static Path	changeExtension(Path path, String extension)	Deprecated. to be removed in favor of changeFilenameExtension(Path, String).
static Path	changeFilenameBase(Path path, String base)	Changes the base of the path's filename, preserving the extension(s), if any.
static Path	changeFilenameExtension(Path path, String extension)	Changes the last extension of a path's filename and returns a new path with the filename with the new extension.
static Path	checkArgumentAbsolute(Path path)	Ensures that a path is absolute.
static void	checkArgumentDisjoint(Path path1, Path path2)	Ensures two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.
static Path	checkArgumentSubPath(Path basePath, Path subPath)	Ensures one path is a subpath of another; that is, they both share a base path with no backtracking.
static Comparator<Path>	filenameComparator()	Returns a general path filename comparator with neutral comparison across locales.
static Comparator<Path>	filenameComparator(Collator collator)	Returns a path filename comparator using the given collator.
static Comparator<Path>	filenameComparator(Locale locale)	Returns a path filename comparator for the given locale.
static Stream<String>	filenameExtensions(Path path)	Returns all the possible extensions of a path's filename, from the most specific to the most general.
static Optional<String>	findFilename(Path path)	Return a path's filename, if any, as a string.
static Optional<String>	findFilenameExtension(Path path)	Extracts the extension from a path's filename.
static Iterable<String>	getExtensions(Path path)	Returns all the possible extensions of a path's filename, from the most specific to the most general.
static Path	getPath(FileSystem fileSystem, Collection<String> names)	Converts a sequence of one or more path strings to a Path by joining them with the given file system.
static boolean	isDisjoint(Path path1, Path path2)	Determines whether two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.
static boolean	isDotfile(Path path)	Determines whether the path is for a so-called "dotfile", the filename of which begins with a dot but is neither "." or "..".
static boolean	isSubPath(Path basePath, Path subPath)	Determines whether one path is a subpath of another; that is, they both share a base path with no backtracking.
static Path	removeExtension(Path path)	Deprecated. to be removed in favor of removeFilenameExtension(Path).
static Path	removeFilenameExtension(Path path)	Removes the last extension, if any, of a path's filename and returns a new filename with no extension.
static Path	resolve(Path path, String... otherNames)	Resolve the given path names against the paths formed by the given names.
static Path	resolve(Path path, Collection<String> otherNames)	Resolve the given path names against the paths formed by the given names.

Methods inherited from class java.lang.Object

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

Method Details

changeBase

public static Path changeBase(@Nonnull
 Path path,
 Path oldBasePath,
 Path newBasePath)

Changes a path from one base to another. For example, /example/base1/test.txt changed from base /example/base1/ to base /example/base2/level2/ yields /example/base2/level2/test.txt. If the old and new base paths are the same, a path equal to the given path is returned.

The paths are normalized before the base is changed.

Parameters:

path - The path the base of which to change.

oldBasePath - The current base path.

newBasePath - The base path of the new path to return .

Returns:

A new path constructed by relativizing the path to the old base path and resolving the resulting path against the new base path.

Throws:

IllegalArgumentException - if the old base path is not a base path (or the same path) of the given path.

See Also:

• Path.relativize(Path)
• Path.resolveSibling(Path)

checkArgumentAbsolute

public static Path checkArgumentAbsolute(@Nonnull
 Path path)

Ensures that a path is absolute.

Parameters:

path - The path to check to be absolute.

Returns:

The given path.

Throws:

IllegalArgumentException - if the given path is not absolute.

See Also:

• Path.isAbsolute()

checkArgumentSubPath

public static Path checkArgumentSubPath(@Nonnull
 Path basePath,
 @Nonnull
 Path subPath)

Ensures one path is a subpath of another; that is, they both share a base path with no backtracking. This method allows the paths to be identical.

Parameters:

basePath - The base path against which the other path will be compared.

subPath - The potential subpath.

Returns:

The given subpath.

Throws:

IllegalArgumentException - if the given subpath is not a subpath of (or the same path as) the base path.

See Also:

• isSubPath(Path, Path)

checkArgumentDisjoint

public static void checkArgumentDisjoint(@Nonnull
 Path path1,
 @Nonnull
 Path path2)

Ensures two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.

Parameters:

path1 - The first path to compare.

path2 - The second path.

Throws:

IllegalArgumentException - if the two path trees overlap.

See Also:

• isDisjoint(Path, Path)

getPath

public static Path getPath(@Nonnull
 FileSystem fileSystem,
 @Nonnull
 Collection<String> names)

Converts a sequence of one or more path strings to a Path by joining them with the given file system.

API Note:

This method is equivalent to FileSystem.getPath(String, String...) and is provided as a convenience for programmatic path construction that may have collected all the path strings into a single collection.

Implementation Specification:

This implementation delegates to FileSystem.getPath(String, String...) and adheres to the restrictions of that method.

Parameters:

fileSystem - The file system to use in creating the path.

names - The path names to be joined to form the path string.

Returns:

The resulting path.

Throws:

IllegalArgumentException - if no names are provided.

InvalidPathException - If the path string cannot be converted.

See Also:

• FileSystem.getPath(String, String...)

isDisjoint

public static boolean isDisjoint(@Nonnull
 Path path1,
 @Nonnull
 Path path2)

Determines whether two paths are disjoint, that is, neither one is a subpath of (or equal to) the other.

Parameters:

path1 - The first path to compare.

path2 - The second path.

Returns:

true if the two path trees do not overlap.

See Also:

• isSubPath(Path, Path)

isSubPath

public static boolean isSubPath(@Nonnull
 Path basePath,
 @Nonnull
 Path subPath)

Determines whether one path is a subpath of another; that is, they both share a base path with no backtracking. This method allows the paths to be identical.

Parameters:

basePath - The base path against which the other path will be compared.

subPath - The potential subpath.

Returns:

true if the given subpath is truly a subpath of (or the same path as) the base path.

resolve

public static Path resolve(@Nonnull
 Path path,
 @Nonnull
 String... otherNames)

Resolve the given path names against the paths formed by the given names. If no other names are given, the path itself is returned.

API Note:

This method is equivalent to calling Path.resolve(String) as many times as needed, or first calling FileSystem.getPath(String, String...) and resolving the resulting path against the original path.

Implementation Specification:

This implementation delegates to resolve(Path, Collection).

Parameters:

path - The path against which the other names will be resolved.

otherNames - The path names to be joined sequentially and resolved in order to resolve against the given path; may be empty.

Returns:

The resulting path.

Throws:

InvalidPathException - If the path string cannot be converted.

resolve

public static Path resolve(@Nonnull
 Path path,
 @Nonnull
 Collection<String> otherNames)

Resolve the given path names against the paths formed by the given names. If no other names are given, the path itself is returned.

API Note:

This method is equivalent to calling Path.resolve(String) as many times as needed, or first calling FileSystem.getPath(String, String...) and resolving the resulting path against the original path.

Implementation Specification:

This implementation delegates to getPath(FileSystem, Collection) and then resolves the resulting path against the given path.

Parameters:

path - The path against which the other names will be resolved.

otherNames - The path names to be joined sequentially and resolved in order to resolve against the given path; may be empty.

Returns:

The resulting path.

Throws:

InvalidPathException - If the path string cannot be converted.

findFilename

public static Optional<String> findFilename(@Nonnull
 Path path)

Return a path's filename, if any, as a string.

Implementation Specification:

This is a convenience method for Path.getFileName().

Parameters:

path - The path to examine.

Returns:

The path's filename, which may not be present, as a string.

filenameComparator

public static Comparator<Path> filenameComparator()

Returns a general path filename comparator with neutral comparison across locales. The comparator sorts the base filename and extension separately, and ignores the rest of the path.

Implementation Specification:

This implementation uses a collator that takes into account differences in case and accents.

Returns:

A neutral path filename comparator for the root locale.

See Also:

• Locale.ROOT
• Filenames.comparator()

filenameComparator

public static Comparator<Path> filenameComparator(@Nonnull
 Locale locale)

Returns a path filename comparator for the given locale. The comparator sorts the base filename and extension separately, and ignores the rest of the path.

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 path filename comparator for the given locale.

See Also:

• Filenames.comparator(Locale)

filenameComparator

public static Comparator<Path> filenameComparator(@Nonnull
 Collator collator)

Returns a path filename comparator using the given collator. The comparator sorts the base filename and extension separately, and ignores the rest of the path.

Parameters:

collator - The collator to use for comparisons.

Returns:

A path filename comparator using the given collator.

See Also:

• Filenames.comparator(Collator)

isDotfile

public static boolean isDotfile(@Nonnull
 Path path)

Determines whether the path is for a so-called "dotfile", the filename of which begins with a dot but is neither "." or "..". This method does not make a distinction between files and directories.

Parameters:

path - The path to check.

Returns:

true if the path contains a filename that is considered a dotfile.

See Also:

• Why do some file/folder names on Windows have a dot in front of them?
• Dotfiles
• Path.getFileName()
• Filenames.isDotfileFilename(CharSequence)

appendFilenameBase

public static Path appendFilenameBase(@Nonnull
 Path path,
 @Nonnull
 CharSequence charSequence)

Appends a given string to the end of the path's 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.

Implementation Specification:

This implementation delegates to Filenames.appendBase(String, CharSequence).

Parameters:

path - The path to examine.

charSequence - The characters to append to the filename.

Returns:

A path with the given character sequence appended before the filename extension, if any.

Throws:

IllegalArgumentException - if the given path has no filename.

changeFilenameBase

public static Path changeFilenameBase(@Nonnull
 Path path,
 @Nonnull
 String base)

Changes the base of the path's 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.

Implementation Specification:

This method delegates to Filenames.changeBase(String, String).

Parameters:

path - The path to examine.

base - The new filename base to set.

Returns:

The path with the new filename base.

Throws:

NullPointerException - if the given path's filename and/or the new base is null.

IllegalArgumentException - if the given path's filename and/or the new base is empty.

filenameExtensions

public static Stream<String> filenameExtensions(Path path)

Returns all the possible extensions of a path's filename, from the most specific to the most general. If the path has no filename, no extensions are returned.

For example for the path path/to/example.foo.bar the following would be returned in order:

1. foo.bar
2. bar

Implementation Specification:

This implementation delegates to Filenames.extensions(CharSequence).

Parameters:

path - The path for which extensions should be returned.

Returns:

A stream of extensions of the given path's filename.

See Also:

• Path.getFileName()

getExtensions

public static Iterable<String> getExtensions(Path path)

Returns all the possible extensions of a path's filename, from the most specific to the most general. If the path has no filename, no extensions are returned.

For example for the path path/to/example.foo.bar the following would be returned in order:

1. foo.bar
2. bar

Implementation Specification:

This implementation delegates to Filenames.getExtensions(CharSequence).

Parameters:

path - The path for which extensions should be returned.

Returns:

An iterable to iterate over the extensions of the given path's filename.

See Also:

• Path.getFileName()

addExtension

@Deprecated
public static Path addExtension(@Nonnull
 Path path,
 @Nonnull
 String extension)

Deprecated.

to be removed in favor of addFilenameExtension(Path, String).

Adds the given extension to a path and returns the new path with the new extension. The filename is not checked to see if it currently has an extension.

Implementation Specification:

This method delegates to addFilenameExtension(Path, String).

Parameters:

path - The path to which to add an extension.

extension - The extension to add.

Returns:

The path with the new extension.

Throws:

IllegalArgumentException - If a filename is not present.

See Also:

• Filenames.addExtension(String, String)

addFilenameExtension

public static Path addFilenameExtension(@Nonnull
 Path path,
 @Nonnull
 String extension)

Adds the given extension to a path and returns the new path with the new extension. The filename is not checked to see if it currently has an extension.

Implementation Specification:

This method delegates to Filenames.addExtension(String, String).

Parameters:

path - The path to which to add an extension.

extension - The extension to add.

Returns:

The path with the new extension.

Throws:

IllegalArgumentException - If a filename is not present.

See Also:

• Filenames.addExtension(String, String)

changeExtension

@Deprecated
public static Path changeExtension(@Nonnull
 Path path,
 @Nullable
 String extension)

Deprecated.

to be removed in favor of changeFilenameExtension(Path, String).

Changes the last extension of a path's filename and returns a new path with the filename with the new extension. If the filename does not currently have an extension, one will be added.

Implementation Specification:

This method delegates to changeFilenameExtension(Path, String).

Parameters:

path - The path for which an extension will be changed.

extension - The extension to set, or null if the extension should be removed.

Returns:

The path with the filename with the new extension.

Throws:

IllegalArgumentException - If a filename is not present, or if the name is just a "/".

See Also:

• Filenames.changeExtension(String, String)

changeFilenameExtension

public static Path changeFilenameExtension(@Nonnull
 Path path,
 @Nullable
 String extension)

Changes the last extension of a path's filename and returns a new path with the filename with the new extension. If the filename does not currently have an extension, one will be added.

Implementation Specification:

This method delegates to Filenames.changeExtension(String, String).

Parameters:

path - The path for which an extension will be changed.

extension - The extension to set, or null if the extension should be removed.

Returns:

The path with the filename with the new extension.

Throws:

IllegalArgumentException - If a filename is not present, or if the name is just a "/".

See Also:

• Filenames.changeExtension(String, String)

findFilenameExtension

public static Optional<String> findFilenameExtension(@Nonnull
 Path path)

Extracts the extension from a path's filename.

Parameters:

path - The path to examine.

Returns:

The extension (not including '.') of the path's filename if any, which may not be present.

See Also:

• Filenames.findExtension(String)

removeExtension

@Deprecated
public static Path removeExtension(@Nonnull
 Path path)

Deprecated.

to be removed in favor of removeFilenameExtension(Path).

Removes the last extension, if any, of a path's filename and returns a new filename with no extension.

Implementation Specification:

This method delegates to removeFilenameExtension(Path).

Parameters:

path - The path for which an extension will be removed.

Returns:

The path with the filename with no extension.

See Also:

• Filenames.removeExtension(String)

removeFilenameExtension

public static Path removeFilenameExtension(@Nonnull
 Path path)

Removes the last extension, if any, of a path's filename and returns a new filename with no extension.

Implementation Specification:

This method delegates to Filenames.removeExtension(String).

Parameters:

path - The path for which an extension will be removed.

Returns:

The path with the filename with no extension.

See Also:

• Filenames.removeExtension(String)

byBaseFilename

public static Predicate<Path> byBaseFilename(@Nonnull
 String baseFilename)

Returns a predicate for matching paths by a base filename. Only paths that have a filename and which filename has the given base name (the given base name followed by one or more filename extensions) will pass the predicate.

Parameters:

baseFilename - The filename base name to match.

Returns:

A predicate for matching path filenames against the given base name.

See Also:

• Filenames.getBaseFilenamePattern(String)

byFilenamePattern

public static Predicate<Path> byFilenamePattern(@Nonnull
 Pattern filenamePattern)

Returns a predicate for a given filename pattern. Only paths that have a filename and which filename matches the given filename pattern will pass the predicate.

Parameters:

filenamePattern - The pattern for matching a filename.

Returns:

A predicate for matching path filenames against the given pattern.