Package org.eclipse.core.runtime

Class Path

  • All Implemented Interfaces:
    Cloneable, IPath
    public class Path
extends Object
implements IPath, Cloneable
    The standard implementation of the IPath interface. Paths are always maintained in canonicalized form. That is, parent references (i.e., ../../) and duplicate separators are resolved. For example, 
         new Path("/a/b").append("../foo/bar")
    will yield the path 
         /a/foo/bar

    This class can be used without OSGi running.

    This class is not intended to be subclassed by clients but may be instantiated.

    See Also:
    IPath
    Restriction:
    This class is not intended to be subclassed by clients.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Path EMPTY
      Constant value containing the empty path with no device on the local file system.
      static Path ROOT
      Constant value containing the root path with no device on the local file system.

    • Constructor Summary

      Constructors 
      Constructor Description
      Path​(String fullPath)
      Constructs a new path from the given string path.
      Path​(String device, String path)
      Constructs a new path from the given device id and string path.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      IPath addFileExtension​(String extension)
      Returns a new path which is the same as this path but with the given file extension added.
      IPath addTrailingSeparator()
      Returns a path with the same segments as this path but with a trailing separator added.
      IPath append​(String tail)
      Returns the canonicalized path obtained from the concatenation of the given string path to the end of this path.
      IPath append​(IPath tail)
      Returns the canonicalized path obtained from the concatenation of the given path's segments to the end of this path.
      Object clone()
      Returns a copy of this path.
      boolean equals​(Object obj)
      Returns whether this path equals the given object.
      static Path forPosix​(String fullPath)
      Constructs a new POSIX path from the given string path.
      static Path forWindows​(String fullPath)
      Constructs a new Windows path from the given string path.
      static IPath fromOSString​(String pathString)
      Constructs a new path from the given string path.
      static IPath fromPortableString​(String pathString)
      Constructs a new path from the given path string.
      String getDevice()
      Returns the device id for this path, or null if this path has no device id.
      String getFileExtension()
      Returns the file extension portion of this path, or null if there is none.
      int hashCode()  
      boolean hasTrailingSeparator()
      Returns whether this path has a trailing separator.
      boolean isAbsolute()
      Returns whether this path is an absolute path (ignoring any device id).
      boolean isEmpty()
      Returns whether this path has no segments and is not a root path.
      boolean isPrefixOf​(IPath anotherPath)
      Returns whether this path is a prefix of the given path.
      boolean isRoot()
      Returns whether this path is a root path.
      boolean isUNC()
      Returns a boolean value indicating whether or not this path is considered to be in UNC form.
      boolean isValidPath​(String path)
      Returns whether the given string is syntactically correct as a path, on this path's file system.
      static boolean isValidPosixPath​(String path)
      Returns whether the given string is syntactically correct as a path on a POSIX file system.
      static boolean isValidPosixSegment​(String segment)
      Returns whether the given string is valid as a segment in a path on a POSIX file system.
      boolean isValidSegment​(String segment)
      Returns whether the given string is valid as a segment in this path.
      static boolean isValidWindowsPath​(String path)
      Returns whether the given string is syntactically correct as a path on the Windows file system.
      static boolean isValidWindowsSegment​(String segment)
      Returns whether the given string is valid as a segment in a path on the Windows file system.
      String lastSegment()
      Returns the last segment of this path, or null if it does not have any segments.
      IPath makeAbsolute()
      Returns an absolute path with the segments and device id of this path.
      IPath makeRelative()
      Returns a relative path with the segments and device id of this path.
      IPath makeRelativeTo​(IPath base)
      Returns a path equivalent to this path, but relative to the given base path if possible.
      IPath makeUNC​(boolean toUNC)
      Return a new path which is the equivalent of this path converted to UNC form (if the given boolean is true) or this path not as a UNC path (if the given boolean is false).
      int matchingFirstSegments​(IPath anotherPath)
      Returns a count of the number of segments which match in this path and the given path (device ids are ignored), comparing in increasing segment number order.
      IPath removeFileExtension()
      Returns a new path which is the same as this path but with the file extension removed.
      IPath removeFirstSegments​(int count)
      Returns a copy of this path with the given number of segments removed from the beginning.
      IPath removeLastSegments​(int count)
      Returns a copy of this path with the given number of segments removed from the end.
      IPath removeTrailingSeparator()
      Returns a path with the same segments as this path but with a trailing separator removed.
      String segment​(int index)
      Returns the specified segment of this path, or null if the path does not have such a segment.
      int segmentCount()
      Returns the number of segments in this path.
      String[] segments()
      Returns the segments in this path in order.
      IPath setDevice​(String value)
      Returns a new path which is the same as this path but with the given device id.
      File toFile()
      Returns a java.io.File corresponding to this path.
      String toOSString()
      Returns a string representation of this path which uses the platform-dependent path separator defined by java.io.File.
      String toPortableString()
      Returns a platform-neutral string representation of this path.
      String toString()
      Returns a string representation of this path, including its device id.
      IPath uptoSegment​(int count)
      Returns a copy of this path truncated after the given number of segments.

    • Field Detail

      • EMPTY

        public static final Path EMPTY
        Constant value containing the empty path with no device on the local file system.

      • ROOT

        public static final Path ROOT
        Constant value containing the root path with no device on the local file system.

    • Constructor Detail

      • Path

        public Path​(String fullPath)
        Constructs a new path from the given string path. The string path must represent a valid file system path on the local file system. The path is canonicalized and double slashes are removed except at the beginning. (to handle UNC paths). All forward slashes ('/') are treated as segment delimiters, and any segment and device delimiters for the local file system are also respected (such as colon (':') and backslash ('\') on some file systems). This constructor should be used if the string path if for the local file system.
        Parameters:
        fullPath - the string path
        See Also:
        isValidPath(String)

      • Path

        public Path​(String device,
            String path)
        Constructs a new path from the given device id and string path. The given string path must be valid. The path is canonicalized and double slashes are removed except at the beginning (to handle UNC paths). All forward slashes ('/') are treated as segment delimiters, and any segment delimiters for the local file system are also respected (such as backslash ('\') on some file systems).
        Parameters:
        device - the device id
        path - the string path
        See Also:
        isValidPath(String), setDevice(String)

    • Method Detail

      • fromOSString

        public static IPath fromOSString​(String pathString)
        Constructs a new path from the given string path. The string path must represent a valid file system path on the local file system. The path is canonicalized and double slashes are removed except at the beginning. (to handle UNC paths). All forward slashes ('/') are treated as segment delimiters, and any segment and device delimiters for the local file system are also respected.
        Parameters:
        pathString - the portable string path
        Since:
        3.1
        See Also:
        IPath.toPortableString()

      • fromPortableString

        public static IPath fromPortableString​(String pathString)
        Constructs a new path from the given path string. The path string must have been produced by a previous call to IPath.toPortableString.
        Parameters:
        pathString - the portable path string
        Since:
        3.1
        See Also:
        IPath.toPortableString()

      • forPosix

        public static Path forPosix​(String fullPath)
        Constructs a new POSIX path from the given string path. The string path must represent a valid file system path on a POSIX file system. The path is canonicalized and double slashes are removed except at the beginning (to handle UNC paths). All forward slashes ('/') are treated as segment delimiters. This factory method should be used if the string path is for a POSIX file system.
        Parameters:
        fullPath - the string path
        Since:
        3.7
        See Also:
        isValidPosixPath(String)

      • forWindows

        public static Path forWindows​(String fullPath)
        Constructs a new Windows path from the given string path. The string path must represent a valid file system path on the Windows file system. The path is canonicalized and double slashes are removed except at the beginning (to handle UNC paths). All forward slashes ('/') are treated as segment delimiters, and any segment ('\') and device (':') delimiters for the Windows file system are also respected. This factory method should be used if the string path is for the Windows file system.
        Parameters:
        fullPath - the string path
        Since:
        3.7
        See Also:
        isValidWindowsPath(String)

      • addFileExtension

        public IPath addFileExtension​(String extension)
        Description copied from interface: IPath
        Returns a new path which is the same as this path but with the given file extension added. If this path is empty, root or has a trailing separator, this path is returned. If this path already has an extension, the existing extension is left and the given extension simply appended. Clients wishing to replace the current extension should first remove the extension and then add the desired one.

        The file extension portion is defined as the string following the last period (".") character in the last segment. The given extension should not include a leading ".".

        Specified by:
        addFileExtension in interface IPath
        Parameters:
        extension - the file extension to append
        Returns:
        the new path

      • append

        public IPath append​(IPath tail)
        Description copied from interface: IPath
        Returns the canonicalized path obtained from the concatenation of the given path's segments to the end of this path. If the given path has a trailing separator, the result will have a trailing separator. The device id of this path is preserved (the one of the given path is ignored). Duplicate slashes are removed from the path except at the beginning where the path is considered to be UNC.
        Specified by:
        append in interface IPath
        Parameters:
        tail - the path to concatenate
        Returns:
        the new path

      • append

        public IPath append​(String tail)
        Description copied from interface: IPath
        Returns the canonicalized path obtained from the concatenation of the given string path to the end of this path. The given string path must be a valid path. If it has a trailing separator, the result will have a trailing separator. The device id of this path is preserved (the one of the given string is ignored). Duplicate slashes are removed from the path except at the beginning where the path is considered to be UNC.
        Specified by:
        append in interface IPath
        Parameters:
        tail - the string path to concatenate
        Returns:
        the new path
        See Also:
        IPath.isValidPath(String)

      • clone

        public Object clone()
        Description copied from interface: IPath
        Returns a copy of this path.
        Specified by:
        clone in interface IPath
        Overrides:
        clone in class Object
        Returns:
        the cloned path

      • equals

        public boolean equals​(Object obj)
        Description copied from interface: IPath
        Returns whether this path equals the given object.

        Equality for paths is defined to be: same sequence of segments, same absolute/relative status, and same device. Trailing separators are disregarded. The paths' file systems are disregarded. Paths are not generally considered equal to objects other than paths.

        Specified by:
        equals in interface IPath
        Overrides:
        equals in class Object
        Parameters:
        obj - the other object
        Returns:
        true if the paths are equivalent, and false if they are not

      • getDevice

        public String getDevice()
        Description copied from interface: IPath
        Returns the device id for this path, or null if this path has no device id. Note that the result will end in ':'.
        Specified by:
        getDevice in interface IPath
        Returns:
        the device id, or null
        See Also:
        IPath.setDevice(String)

      • getFileExtension

        public String getFileExtension()
        Description copied from interface: IPath
        Returns the file extension portion of this path, or null if there is none.

        The file extension portion is defined as the string following the last period (".") character in the last segment. If there is no period in the last segment, the path has no file extension portion. If the last segment ends in a period, the file extension portion is the empty string.

        Specified by:
        getFileExtension in interface IPath
        Returns:
        the file extension or null

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object

      • hasTrailingSeparator

        public boolean hasTrailingSeparator()
        Description copied from interface: IPath
        Returns whether this path has a trailing separator.

        Note: In the root path ("/"), the separator is considered to be leading rather than trailing.

        Specified by:
        hasTrailingSeparator in interface IPath
        Returns:
        true if this path has a trailing separator, and false otherwise
        See Also:
        IPath.addTrailingSeparator(), IPath.removeTrailingSeparator()

      • isAbsolute

        public boolean isAbsolute()
        Description copied from interface: IPath
        Returns whether this path is an absolute path (ignoring any device id).

        Absolute paths start with a path separator. A root path, like / or C:/, is considered absolute. UNC paths are always absolute.

        Specified by:
        isAbsolute in interface IPath
        Returns:
        true if this path is an absolute path, and false otherwise

      • isEmpty

        public boolean isEmpty()
        Description copied from interface: IPath
        Returns whether this path has no segments and is not a root path.
        Specified by:
        isEmpty in interface IPath
        Returns:
        true if this path is empty, and false otherwise

      • isPrefixOf

        public boolean isPrefixOf​(IPath anotherPath)
        Description copied from interface: IPath
        Returns whether this path is a prefix of the given path. To be a prefix, this path's segments must appear in the argument path in the same order, and their device ids must match.

        An empty path is a prefix of all paths with the same device; a root path is a prefix of all absolute paths with the same device.

        Specified by:
        isPrefixOf in interface IPath
        Parameters:
        anotherPath - the other path
        Returns:
        true if this path is a prefix of the given path, and false otherwise

      • isRoot

        public boolean isRoot()
        Description copied from interface: IPath
        Returns whether this path is a root path.

        The root path is the absolute non-UNC path with zero segments; e.g., / or C:/. The separator is considered a leading separator, not a trailing one.

        Specified by:
        isRoot in interface IPath
        Returns:
        true if this path is a root path, and false otherwise

      • isUNC

        public boolean isUNC()
        Description copied from interface: IPath
        Returns a boolean value indicating whether or not this path is considered to be in UNC form. Return false if this path has a device set or if the first 2 characters of the path string are not Path.SEPARATOR.
        Specified by:
        isUNC in interface IPath
        Returns:
        boolean indicating if this path is UNC

      • isValidPath

        public boolean isValidPath​(String path)
        Description copied from interface: IPath
        Returns whether the given string is syntactically correct as a path, on this path's file system. The device id is the prefix up to and including the device separator for the file system of this path; the path proper is everything to the right of it, or the entire string if there is no device separator. When this path's file system has no meaningful device separator, the entire string is treated as the path proper. The device id is not checked for validity; the path proper is correct if each of the segments in its canonicalized form is valid.
        Specified by:
        isValidPath in interface IPath
        Parameters:
        path - the path to check
        Returns:
        true if the given string is a valid path, and false otherwise
        See Also:
        IPath.isValidSegment(String)

      • isValidPosixPath

        public static boolean isValidPosixPath​(String path)
        Returns whether the given string is syntactically correct as a path on a POSIX file system. The path is correct if each of the segments in its canonicalized form is valid.
        Parameters:
        path - the path to check
        Returns:
        true if the given string is a valid path, and false otherwise
        Since:
        3.7
        See Also:
        isValidPosixSegment(String)

      • isValidWindowsPath

        public static boolean isValidWindowsPath​(String path)
        Returns whether the given string is syntactically correct as a path on the Windows file system. The device id is the prefix up to and including the device separator (':'); the path proper is everything to the right of it, or the entire string if there is no device separator. The device id is not checked for validity; the path proper is correct if each of the segments in its canonicalized form is valid.
        Parameters:
        path - the path to check
        Returns:
        true if the given string is a valid path, and false otherwise
        Since:
        3.7
        See Also:
        isValidWindowsSegment(String)

      • isValidSegment

        public boolean isValidSegment​(String segment)
        Description copied from interface: IPath
        Returns whether the given string is valid as a segment in this path. The rules for valid segments are as follows:
        • the empty string is not valid
        • any string containing the slash character ('/') is not valid
        • any string containing segment or device separator characters on this path's file system, such as the backslash ('\') and colon (':') on some file systems, is not valid
        Specified by:
        isValidSegment in interface IPath
        Parameters:
        segment - the path segment to check
        Returns:
        true if the given path segment is valid, and false otherwise

      • isValidPosixSegment

        public static boolean isValidPosixSegment​(String segment)
        Returns whether the given string is valid as a segment in a path on a POSIX file system. The rules for valid segments are as follows:
        • the empty string is not valid
        • any string containing the slash character ('/') is not valid
        Parameters:
        segment - the path segment to check
        Returns:
        true if the given path segment is valid, and false otherwise
        Since:
        3.7

      • isValidWindowsSegment

        public static boolean isValidWindowsSegment​(String segment)
        Returns whether the given string is valid as a segment in a path on the Windows file system. The rules for valid segments are as follows:
        • the empty string is not valid
        • any string containing the slash character ('/') is not valid
        • any string containing segment ('\') or device (':') separator characters is not valid
        Parameters:
        segment - the path segment to check
        Returns:
        true if the given path segment is valid, and false otherwise
        Since:
        3.7

      • lastSegment

        public String lastSegment()
        Description copied from interface: IPath
        Returns the last segment of this path, or null if it does not have any segments.
        Specified by:
        lastSegment in interface IPath
        Returns:
        the last segment of this path, or null

      • makeAbsolute

        public IPath makeAbsolute()
        Description copied from interface: IPath
        Returns an absolute path with the segments and device id of this path. Absolute paths start with a path separator. If this path is absolute, it is simply returned.
        Specified by:
        makeAbsolute in interface IPath
        Returns:
        the new path

      • makeRelative

        public IPath makeRelative()
        Description copied from interface: IPath
        Returns a relative path with the segments and device id of this path. Absolute paths start with a path separator and relative paths do not. If this path is relative, it is simply returned.
        Specified by:
        makeRelative in interface IPath
        Returns:
        the new path

      • makeRelativeTo

        public IPath makeRelativeTo​(IPath base)
        Returns a path equivalent to this path, but relative to the given base path if possible.

        The path is only made relative if the base path if both paths have the same device and have a non-zero length common prefix. If the paths have different devices, or no common prefix, then this path is simply returned. If the path is successfully made relative, then appending the returned path to the base will always produce a path equal to this path.

        Specified by:
        makeRelativeTo in interface IPath
        Parameters:
        base - The base path to make this path relative to
        Returns:
        A path relative to the base path, or this path if it could not be made relative to the given base
        Since:
        org.eclipse.equinox.common 3.5

      • makeUNC

        public IPath makeUNC​(boolean toUNC)
        Description copied from interface: IPath
        Return a new path which is the equivalent of this path converted to UNC form (if the given boolean is true) or this path not as a UNC path (if the given boolean is false). If UNC, the returned path will not have a device and the first 2 characters of the path string will be Path.SEPARATOR. If not UNC, the first 2 characters of the returned path string will not be Path.SEPARATOR.
        Specified by:
        makeUNC in interface IPath
        Parameters:
        toUNC - true if converting to UNC, false otherwise
        Returns:
        the new path, either in UNC form or not depending on the boolean parameter

      • matchingFirstSegments

        public int matchingFirstSegments​(IPath anotherPath)
        Description copied from interface: IPath
        Returns a count of the number of segments which match in this path and the given path (device ids are ignored), comparing in increasing segment number order.
        Specified by:
        matchingFirstSegments in interface IPath
        Parameters:
        anotherPath - the other path
        Returns:
        the number of matching segments

      • removeFileExtension

        public IPath removeFileExtension()
        Description copied from interface: IPath
        Returns a new path which is the same as this path but with the file extension removed. If this path does not have an extension, this path is returned.

        The file extension portion is defined as the string following the last period (".") character in the last segment. If there is no period in the last segment, the path has no file extension portion. If the last segment ends in a period, the file extension portion is the empty string.

        Specified by:
        removeFileExtension in interface IPath
        Returns:
        the new path

      • removeFirstSegments

        public IPath removeFirstSegments​(int count)
        Description copied from interface: IPath
        Returns a copy of this path with the given number of segments removed from the beginning. The device id is preserved. The count must be greater or equal zero.

        If the count is zero, this path is returned. This is the only case where the returned path can be absolute. Use IPath.makeRelative() if necessary.

        If the count is greater than zero, the resulting path will always be a relative path.

        If the count equals or exceeds the number of segments in this path, an empty relative path is returned.

        Specified by:
        removeFirstSegments in interface IPath
        Parameters:
        count - the number of segments to remove
        Returns:
        the new path

      • removeLastSegments

        public IPath removeLastSegments​(int count)
        Description copied from interface: IPath
        Returns a copy of this path with the given number of segments removed from the end. The device id is preserved. The number must be greater or equal zero. If the count is zero, this path is returned.

        If this path has a trailing separator, it will still have a trailing separator after the last segments are removed (assuming there are some segments left). If there is no trailing separator, the result will not have a trailing separator. If the number equals or exceeds the number of segments in this path, a path with no segments is returned.

        Specified by:
        removeLastSegments in interface IPath
        Parameters:
        count - the number of segments to remove
        Returns:
        the new path

      • removeTrailingSeparator

        public IPath removeTrailingSeparator()
        Description copied from interface: IPath
        Returns a path with the same segments as this path but with a trailing separator removed. Does nothing if this path does not have at least one segment. The device id is preserved.

        If this path does not have a trailing separator, this path is returned.

        Specified by:
        removeTrailingSeparator in interface IPath
        Returns:
        the new path
        See Also:
        IPath.addTrailingSeparator(), IPath.hasTrailingSeparator()

      • segment

        public String segment​(int index)
        Description copied from interface: IPath
        Returns the specified segment of this path, or null if the path does not have such a segment.
        Specified by:
        segment in interface IPath
        Parameters:
        index - the 0-based segment index
        Returns:
        the specified segment, or null

      • segmentCount

        public int segmentCount()
        Description copied from interface: IPath
        Returns the number of segments in this path.

        Note that both root and empty paths have 0 segments.

        Specified by:
        segmentCount in interface IPath
        Returns:
        the number of segments

      • segments

        public String[] segments()
        Description copied from interface: IPath
        Returns the segments in this path in order.
        Specified by:
        segments in interface IPath
        Returns:
        an array of string segments

      • setDevice

        public IPath setDevice​(String value)
        Description copied from interface: IPath
        Returns a new path which is the same as this path but with the given device id. The device id must end with a ":". A device independent path is obtained by passing null.

        For example, "C:" and "Server/Volume:" are typical device ids.

        Specified by:
        setDevice in interface IPath
        Parameters:
        value - the device id or null
        Returns:
        a new path
        See Also:
        IPath.getDevice()

      • toFile

        public File toFile()
        Description copied from interface: IPath
        Returns a java.io.File corresponding to this path.
        Specified by:
        toFile in interface IPath
        Returns:
        the file corresponding to this path

      • toOSString

        public String toOSString()
        Description copied from interface: IPath
        Returns a string representation of this path which uses the platform-dependent path separator defined by java.io.File. This method is like toString() except that the latter always uses the same separator (/) regardless of platform.

        This string is suitable for passing to java.io.File(String).

        Specified by:
        toOSString in interface IPath
        Returns:
        a platform-dependent string representation of this path

      • toPortableString

        public String toPortableString()
        Description copied from interface: IPath
        Returns a platform-neutral string representation of this path. The format is not specified, except that the resulting string can be passed back to the Path#fromPortableString(String) constructor to produce the exact same path on any platform.

        This string is suitable for passing to Path#fromPortableString(String).

        Specified by:
        toPortableString in interface IPath
        Returns:
        a platform-neutral string representation of this path
        See Also:
        fromPortableString(String)

      • toString

        public String toString()
        Description copied from interface: IPath
        Returns a string representation of this path, including its device id. The same separator, "/", is used on all platforms.

        Example result strings (without and with device id): 

         "/foo/bar.txt"
 "bar.txt"
 "/foo/"
 "foo/"
 ""
 "/"
 "C:/foo/bar.txt"
 "C:bar.txt"
 "C:/foo/"
 "C:foo/"
 "C:"
 "C:/"
        This string is suitable for passing to Path(String).
        Specified by:
        toString in interface IPath
        Overrides:
        toString in class Object
        Returns:
        a string representation of this path
        See Also:
        Path

      • uptoSegment

        public IPath uptoSegment​(int count)
        Description copied from interface: IPath
        Returns a copy of this path truncated after the given number of segments. The number must not be negative. The device id is preserved.

        If this path has a trailing separator, the result will too (assuming there are some segments left). If there is no trailing separator, the result will not have a trailing separator. Copying up to segment zero simply means making an copy with no path segments.

        Specified by:
        uptoSegment in interface IPath
        Parameters:
        count - the segment number at which to truncate the path
        Returns:
        the new path