Package org.eclipse.core.runtime

Interface IPath

All Superinterfaces:
Cloneable
All Known Implementing Classes:
Path
public interface IPath extends Cloneable
A path is an ordered collection of string segments, separated by a standard separator character, "/". A path may also have a leading and/or a trailing separator. Paths may also be prefixed by an optional device id, which includes the character(s) which separate the device id from the rest of the path. For example, "C:" and "Server/Volume:" are typical device ids. A device independent path has null for a device id.

Note that paths are value objects; all operations on paths return a new path; the path that is operated on is unscathed.

UNC paths are denoted by leading double-slashes such as //Server/Volume/My/Path. When a new path is constructed all double-slashes are removed except those appearing at the beginning of the path.

This interface can be used without OSGi running.

This interface is not intended to be implemented by clients.

See Also:
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final char
    DEVICE_SEPARATOR
    Device separator character constant ":" used in paths.
    static final IPath
    EMPTY
    Constant value containing the empty path with no device on the local file system.
    static final IPath
    ROOT
    Constant value containing the root path with no device on the local file system.
    static final char
    SEPARATOR
    Path separator character constant "/" used in paths.

  • Method Summary

    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 path)
    Returns the canonicalized path obtained from the concatenation of the given string path to the end of this path.
    IPath
    append(IPath path)
    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 IPath
    forPosix(String posixPath)
    Constructs a new POSIX path from the given string path.
    static IPath
    forWindows(String windowsPath)
    Constructs a new Windows path from the given string path.
    static IPath
    fromFile(File file)
    Constructs a new IPath from the given File.
    static IPath
    fromOSString(String osPath)
    Constructs a new path from the given string path.
    static IPath
    fromPath(Path path)
    Constructs a new IPath from the given java.nio.file.Path.
    static IPath
    fromPortableString(String portablePath)
    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.
    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.
    boolean
    isValidSegment(String segment)
    Returns whether the given string is valid as a segment in this path.
    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 device)
    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.
    default Path
    toPath()
    Returns a java.nio.file.Path corresponding to this path.
    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 Details

    • SEPARATOR

      static final char SEPARATOR
      Path separator character constant "/" used in paths.
      See Also:

    • DEVICE_SEPARATOR

      static final char DEVICE_SEPARATOR
      Device separator character constant ":" used in paths.
      See Also:

    • EMPTY

      static final IPath EMPTY
      Constant value containing the empty path with no device on the local file system.
      Since:
      3.18

    • ROOT

      static final IPath ROOT
      Constant value containing the root path with no device on the local file system.
      Since:
      3.18

  • Method Details

    • fromOSString

      static IPath fromOSString(String osPath)
      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:
      osPath - the operating-system specific string path
      Returns:
      the IPath representing the given OS specific string path
      Since:
      3.18

    • fromPortableString

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

    • forPosix

      static IPath forPosix(String posixPath)
      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:
      posixPath - the string path
      Returns:
      the IPath representing the given POSIX string path
      Since:
      3.18

    • forWindows

      static IPath forWindows(String windowsPath)
      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:
      windowsPath - the string path
      Returns:
      the IPath representing the given Windows string path
      Since:
      3.18

    • fromFile

      static IPath fromFile(File file)
      Constructs a new IPath from the given File.
      Parameters:
      file - the java.io.File object
      Returns:
      the IPath representing the given File object
      Since:
      3.18

    • fromPath

      static IPath fromPath(Path path)
      Constructs a new IPath from the given java.nio.file.Path.
      Parameters:
      path - the java.nio.file.Path object
      Returns:
      the IPath representing the given Path object
      Since:
      3.18

    • addFileExtension

      IPath addFileExtension(String extension)
      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 ".".

      Parameters:
      extension - the file extension to append
      Returns:
      the new path

    • addTrailingSeparator

      IPath addTrailingSeparator()
      Returns a path with the same segments as this path but with a trailing separator added. This path must have at least one segment.

      If this path already has a trailing separator, this path is returned.

      Returns:
      the new path
      See Also:

    • append

      IPath append(String path)
      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.
      Parameters:
      path - the string path to concatenate
      Returns:
      the new path
      See Also:

    • append

      IPath append(IPath path)
      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.
      Parameters:
      path - the path to concatenate
      Returns:
      the new path

    • clone

      Object clone()
      Returns a copy of this path.
      Returns:
      the cloned path

    • equals

      boolean equals(Object obj)
      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.

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

    • getDevice

      String getDevice()
      Returns the device id for this path, or null if this path has no device id. Note that the result will end in ':'.
      Returns:
      the device id, or null
      See Also:

    • getFileExtension

      String getFileExtension()
      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.

      Returns:
      the file extension or null

    • hasTrailingSeparator

      boolean hasTrailingSeparator()
      Returns whether this path has a trailing separator.

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

      Returns:
      true if this path has a trailing separator, and false otherwise
      See Also:

    • isAbsolute

      boolean isAbsolute()
      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.

      Returns:
      true if this path is an absolute path, and false otherwise

    • isEmpty

      boolean isEmpty()
      Returns whether this path has no segments and is not a root path.
      Returns:
      true if this path is empty, and false otherwise

    • isPrefixOf

      boolean isPrefixOf(IPath anotherPath)
      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.

      Parameters:
      anotherPath - the other path
      Returns:
      true if this path is a prefix of the given path, and false otherwise

    • isRoot

      boolean isRoot()
      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.

      Returns:
      true if this path is a root path, and false otherwise

    • isUNC

      boolean isUNC()
      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.
      Returns:
      boolean indicating if this path is UNC

    • isValidPath

      boolean isValidPath(String path)
      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.
      Parameters:
      path - the path to check
      Returns:
      true if the given string is a valid path, and false otherwise
      See Also:

    • isValidSegment

      boolean isValidSegment(String segment)
      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
      Parameters:
      segment - the path segment to check
      Returns:
      true if the given path segment is valid, and false otherwise

    • lastSegment

      String lastSegment()
      Returns the last segment of this path, or null if it does not have any segments.
      Returns:
      the last segment of this path, or null

    • makeAbsolute

      IPath makeAbsolute()
      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.
      Returns:
      the new path

    • makeRelative

      IPath makeRelative()
      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.
      Returns:
      the new path

    • makeRelativeTo

      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.

      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

      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). 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.
      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

      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.
      Parameters:
      anotherPath - the other path
      Returns:
      the number of matching segments

    • removeFileExtension

      IPath removeFileExtension()
      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.

      Returns:
      the new path

    • removeFirstSegments

      IPath removeFirstSegments(int count)
      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 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.

      Parameters:
      count - the number of segments to remove
      Returns:
      the new path

    • removeLastSegments

      IPath removeLastSegments(int count)
      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.

      Parameters:
      count - the number of segments to remove
      Returns:
      the new path

    • removeTrailingSeparator

      IPath removeTrailingSeparator()
      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.

      Returns:
      the new path
      See Also:

    • segment

      String segment(int index)
      Returns the specified segment of this path, or null if the path does not have such a segment.
      Parameters:
      index - the 0-based segment index
      Returns:
      the specified segment, or null

    • segmentCount

      int segmentCount()
      Returns the number of segments in this path.

      Note that both root and empty paths have 0 segments.

      Returns:
      the number of segments

    • segments

      String[] segments()
      Returns the segments in this path in order.
      Returns:
      an array of string segments

    • setDevice

      IPath setDevice(String device)
      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.

      Parameters:
      device - the device id or null
      Returns:
      a new path
      See Also:

    • toFile

      File toFile()
      Returns a java.io.File corresponding to this path.
      Returns:
      the file corresponding to this path

    • toPath

      default Path toPath()
      Returns a java.nio.file.Path corresponding to this path.
      Returns:
      the path corresponding to this path
      Since:
      3.18

    • toOSString

      String toOSString()
      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).

      Returns:
      a platform-dependent string representation of this path

    • toPortableString

      String toPortableString()
      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).

      Returns:
      a platform-neutral string representation of this path
      Since:
      3.1
      See Also:

    • toString

      String toString()
      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).
      Overrides:
      toString in class Object
      Returns:
      a string representation of this path
      See Also:

    • uptoSegment

      IPath uptoSegment(int count)
      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.

      Parameters:
      count - the segment number at which to truncate the path
      Returns:
      the new path