Class Path
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:
- Restriction:
- This class is not intended to be subclassed by clients.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final Path
Constant value containing the empty path with no device on the local file system.static final Path
Constant value containing the root path with no device on the local file system.Fields inherited from interface org.eclipse.core.runtime.IPath
DEVICE_SEPARATOR, SEPARATOR
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionaddFileExtension
(String extension) Returns a new path which is the same as this path but with the given file extension added.Returns a path with the same segments as this path but with a trailing separator added.Returns the canonicalized path obtained from the concatenation of the given string path to the end of this path.Returns the canonicalized path obtained from the concatenation of the given path's segments to the end of this path.clone()
Returns a copy of this path.boolean
Returns whether this path equals the given object.static Path
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.Returns the device id for this path, ornull
if this path has no device id.Returns the file extension portion of this path, ornull
if there is none.int
hashCode()
boolean
Returns whether this path has a trailing separator.boolean
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.Returns the last segment of this path, ornull
if it does not have any segments.Returns an absolute path with the segments and device id of this path.Returns a relative path with the segments and device id of this path.makeRelativeTo
(IPath base) Returns a path equivalent to this path, but relative to the given base path if possible.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.Returns a new path which is the same as this path but with the file extension removed.removeFirstSegments
(int count) Returns a copy of this path with the given number of segments removed from the beginning.removeLastSegments
(int count) Returns a copy of this path with the given number of segments removed from the end.Returns a path with the same segments as this path but with a trailing separator removed.segment
(int index) Returns the specified segment of this path, ornull
if the path does not have such a segment.int
Returns the number of segments in this path.String[]
segments()
Returns the segments in this path in order.Returns a new path which is the same as this path but with the given device id.toFile()
Returns ajava.io.File
corresponding to this path.Returns a string representation of this path which uses the platform-dependent path separator defined byjava.io.File
.Returns a platform-neutral string representation of this path.toString()
Returns a string representation of this path, including its device id.uptoSegment
(int count) Returns a copy of this path truncated after the given number of segments.
-
Field Details
-
EMPTY
Constant value containing the empty path with no device on the local file system.Instead of referencing this constants it is recommended to use
IPath.EMPTY
instead.- See Also:
-
ROOT
Constant value containing the root path with no device on the local file system.Instead of referencing this constants it is recommended to use
IPath.ROOT
instead.- See Also:
-
-
Constructor Details
-
Path
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:
-
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 idpath
- the string path- See Also:
-
-
Method Details
-
fromOSString
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.Instead of calling this method it is recommended to call
IPath.fromOSString(String)
instead.- Parameters:
pathString
- the operating-system specific string path- Returns:
- the IPath representing the given OS specific string path
- Since:
- 3.1
- See Also:
-
fromPortableString
Constructs a new path from the given path string. The path string must have been produced by a previous call toIPath.toPortableString
.Instead of calling this method it is recommended to call
IPath.fromPortableString(String)
instead.- Parameters:
pathString
- the portable path string- Returns:
- the IPath representing the given portable string path
- Since:
- 3.1
- See Also:
-
forPosix
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.Instead of calling this method it is recommended to call
IPath.forPosix(String)
instead.- Parameters:
fullPath
- the string path- Returns:
- the IPath representing the given POSIX string path
- Since:
- 3.7
- See Also:
-
forWindows
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.Instead of calling this method it is recommended to call
IPath.forWindows(String)
instead.- Parameters:
fullPath
- the string path- Returns:
- the IPath representing the given Windows string path
- Since:
- 3.7
- See Also:
-
addFileExtension
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 interfaceIPath
- Parameters:
extension
- the file extension to append- Returns:
- the new path
-
addTrailingSeparator
Description copied from interface:IPath
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.
- Specified by:
addTrailingSeparator
in interfaceIPath
- Returns:
- the new path
- See Also:
-
append
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. -
append
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. -
clone
Description copied from interface:IPath
Returns a copy of this path. -
equals
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.
-
getDevice
Description copied from interface:IPath
Returns the device id for this path, ornull
if this path has no device id. Note that the result will end in ':'. -
getFileExtension
Description copied from interface:IPath
Returns the file extension portion of this path, ornull
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 interfaceIPath
- Returns:
- the file extension or
null
-
hashCode
public int hashCode() -
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 interfaceIPath
- Returns:
true
if this path has a trailing separator, andfalse
otherwise- See Also:
-
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
/
orC:/
, is considered absolute. UNC paths are always absolute.- Specified by:
isAbsolute
in interfaceIPath
- Returns:
true
if this path is an absolute path, andfalse
otherwise
-
isEmpty
public boolean isEmpty()Description copied from interface:IPath
Returns whether this path has no segments and is not a root path. -
isPrefixOf
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 interfaceIPath
- Parameters:
anotherPath
- the other path- Returns:
true
if this path is a prefix of the given path, andfalse
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.,
/
orC:/
. The separator is considered a leading separator, not a trailing one. -
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 notPath.SEPARATOR
. -
isValidPath
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 interfaceIPath
- Parameters:
path
- the path to check- Returns:
true
if the given string is a valid path, andfalse
otherwise- See Also:
-
isValidPosixPath
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, andfalse
otherwise- Since:
- 3.7
- See Also:
-
isValidWindowsPath
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, andfalse
otherwise- Since:
- 3.7
- See Also:
-
isValidSegment
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 interfaceIPath
- Parameters:
segment
- the path segment to check- Returns:
true
if the given path segment is valid, andfalse
otherwise
-
isValidPosixSegment
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, andfalse
otherwise- Since:
- 3.7
-
isValidWindowsSegment
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, andfalse
otherwise- Since:
- 3.7
-
lastSegment
Description copied from interface:IPath
Returns the last segment of this path, ornull
if it does not have any segments.- Specified by:
lastSegment
in interfaceIPath
- Returns:
- the last segment of this path, or
null
-
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 interfaceIPath
- Returns:
- the new path
-
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 interfaceIPath
- Returns:
- the new path
-
makeRelativeTo
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 interfaceIPath
- 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
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 bePath.SEPARATOR
. If not UNC, the first 2 characters of the returned path string will not bePath.SEPARATOR
. -
matchingFirstSegments
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 interfaceIPath
- Parameters:
anotherPath
- the other path- Returns:
- the number of matching segments
-
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 interfaceIPath
- Returns:
- the new path
-
removeFirstSegments
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 interfaceIPath
- Parameters:
count
- the number of segments to remove- Returns:
- the new path
-
removeLastSegments
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 interfaceIPath
- Parameters:
count
- the number of segments to remove- Returns:
- the new path
-
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 interfaceIPath
- Returns:
- the new path
- See Also:
-
segment
Description copied from interface:IPath
Returns the specified segment of this path, ornull
if the path does not have such a segment. -
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 interfaceIPath
- Returns:
- the number of segments
-
segments
Description copied from interface:IPath
Returns the segments in this path in order. -
setDevice
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 passingnull
.For example, "C:" and "Server/Volume:" are typical device ids.
-
toFile
Description copied from interface:IPath
Returns ajava.io.File
corresponding to this path. -
toOSString
Description copied from interface:IPath
Returns a string representation of this path which uses the platform-dependent path separator defined byjava.io.File
. This method is liketoString()
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 interfaceIPath
- Returns:
- a platform-dependent string representation of this path
-
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 thePath#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 interfaceIPath
- Returns:
- a platform-neutral string representation of this path
- See Also:
-
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 toPath(String)
. -
uptoSegment
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 interfaceIPath
- Parameters:
count
- the segment number at which to truncate the path- Returns:
- the new path
-