Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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 is not intended to be implemented by clients.

See Also:
  `Path`

Field Summary
`static char` | `DEVICE_SEPARATOR` Device separator character constant ":" used in paths.
`static char` | `SEPARATOR` Path separator character constant "/" used in paths.

Method Summary
`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.
`boolean` | `isValidSegment(String segment)` Returns whether the given string is valid as a segment in a 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` | `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` | `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

### SEPARATOR

    public static final char SEPARATOR

  Path separator character constant "/" used in paths.

  See Also:
    Constant Field Values

### DEVICE_SEPARATOR

    public static final char DEVICE_SEPARATOR

  Device separator character constant ":" used in paths.

  See Also:
    Constant Field Values

Method Detail

### addFileExtension

    public 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

    public 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:
    `hasTrailingSeparator()`, `removeTrailingSeparator()`

### append

    public 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:
    `isValidPath(String)`

### append

    public 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

    public Object clone()

  Returns a copy of this path.

  Returns:
    the cloned path

### equals

    public 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. Paths are not generally considered equal to objects other than paths.

  Parameters:
    `obj` - the other object
  Returns:
    `true` if the paths are equivalent, and `false` if they are not

### getDevice

    public 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:
    `setDevice(String)`

### getFileExtension

    public 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

    public 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:
    `addTrailingSeparator()`, `removeTrailingSeparator()`

### isAbsolute

    public 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

    public 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

    public 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

    public 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

    public 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

    public boolean isValidPath(String path)

  Returns whether the given string is syntactically correct as a path. The device id is the prefix up to and including the first ":"; the path proper is everything to the right of it, or the entire string if there is no ":". 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(String)`

### isValidSegment

    public boolean isValidSegment(String segment)

  Returns whether the given string is valid as a segment in a path. The rules for valid segments are as follows:
  - the empty string is not valid
  - any string containing the colon character (":") is not valid
  - any string containing the slash character ("/") is not valid
  - any string containing the backslash character ("\") is not valid
  - any string starting or ending with a whitespace character is not valid
  - all other strings are valid

  Parameters:
    `segment` - the path segment to check
  Returns:
    `true` if the given path segment is valid, and `false` otherwise
  See Also:
    `Character.isWhitespace(char)`

### lastSegment

    public 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

    public 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

    public 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

### makeUNC

    public 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 parm

### matchingFirstSegments

    public 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

    public 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

    public 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 number must be greater or equal zero. If the count is zero, this path is returned. The resulting path will always be a relative path with respect to this path. If the number 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

    public 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, an empty path is returned.

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

### removeTrailingSeparator

    public 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:
    `addTrailingSeparator()`, `hasTrailingSeparator()`

### segment

    public 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

    public 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

    public String[] segments()

  Returns the segments in this path in order.

  Returns:
    an array of string segments

### setDevice

    public 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:
    `getDevice()`

### toFile

    public File toFile()

  Returns a `java.io.File` corresponding to this path.

  Returns:
    the file corresponding to this path

### toOSString

    public 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

### toString

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

  Returns:
    a string representation of this path
  See Also:
    `Path`

### uptoSegment

    public 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.