public interface IPath extends Cloneable
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.
Path
Modifier and Type | Field and Description |
---|---|
static char |
DEVICE_SEPARATOR
Device separator character constant ":" used in paths.
|
static char |
SEPARATOR
Path separator character constant "/" used in paths.
|
Modifier and Type | Method and 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(IPath path)
Returns the canonicalized path obtained from the
concatenation of the given path's segments to the
end of this path.
|
IPath |
append(String path)
Returns the canonicalized path obtained from the
concatenation of the given string path 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.
|
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 . |
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.
|
static final char SEPARATOR
static final char DEVICE_SEPARATOR
IPath addFileExtension(String extension)
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 ".".
extension
- the file extension to appendIPath addTrailingSeparator()
If this path already has a trailing separator, this path is returned.
hasTrailingSeparator()
,
removeTrailingSeparator()
IPath append(String path)
path
- the string path to concatenateisValidPath(String)
IPath append(IPath path)
path
- the path to concatenateObject clone()
boolean equals(Object obj)
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.
String getDevice()
null
if this
path has no device id. Note that the result will end in ':'.null
setDevice(String)
String getFileExtension()
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.
null
boolean hasTrailingSeparator()
Note: In the root path ("/"), the separator is considered to be leading rather than trailing.
true
if this path has a trailing
separator, and false
otherwiseaddTrailingSeparator()
,
removeTrailingSeparator()
boolean isAbsolute()
Absolute paths start with a path separator.
A root path, like /
or C:/
,
is considered absolute. UNC paths are always absolute.
true
if this path is an absolute path,
and false
otherwiseboolean isEmpty()
true
if this path is empty,
and false
otherwiseboolean isPrefixOf(IPath anotherPath)
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.
anotherPath
- the other pathtrue
if this path is a prefix of the given path,
and false
otherwiseboolean isRoot()
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.
true
if this path is a root path,
and false
otherwiseboolean isUNC()
Path.SEPARATOR
.boolean isValidPath(String path)
path
- the path to checktrue
if the given string is a valid path,
and false
otherwiseisValidSegment(String)
boolean isValidSegment(String segment)
segment
- the path segment to checktrue
if the given path segment is valid,
and false
otherwiseString lastSegment()
null
if it does not have any segments.null
IPath makeAbsolute()
IPath makeRelative()
IPath makeRelativeTo(IPath base)
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.
base
- The base path to make this path relative toIPath makeUNC(boolean toUNC)
Path.SEPARATOR
. If not UNC, the
first 2 characters of the returned path string will not be Path.SEPARATOR
.toUNC
- true if converting to UNC, false otherwiseint matchingFirstSegments(IPath anotherPath)
anotherPath
- the other pathIPath removeFileExtension()
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.
IPath removeFirstSegments(int count)
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.
count
- the number of segments to removeIPath removeLastSegments(int count)
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.
count
- the number of segments to removeIPath removeTrailingSeparator()
If this path does not have a trailing separator, this path is returned.
addTrailingSeparator()
,
hasTrailingSeparator()
String segment(int index)
null
if the path does not have such a segment.index
- the 0-based segment indexnull
int segmentCount()
Note that both root and empty paths have 0 segments.
String[] segments()
IPath setDevice(String device)
null
.
For example, "C:" and "Server/Volume:" are typical device ids.
device
- the device id or null
getDevice()
File toFile()
java.io.File
corresponding to this path.String toOSString()
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)
.
String toPortableString()
Path#fromPortableString(String)
constructor to produce the exact same path on any platform.
This string is suitable for passing to Path#fromPortableString(String)
.
Path.fromPortableString(String)
String toString()
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)
.
IPath uptoSegment(int count)
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.
count
- the segment number at which to truncate the path
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.