/*******************************************************************************
* Copyright (c) 2000, 2008 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.core.runtime;
/**
* 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 <code>null</code> for a device id.
* <p>
* Note that paths are value objects; all operations on paths return a new path;
* the path that is operated on is unscathed.
* </p>
* <p>
* UNC paths are denoted by leading double-slashes such as
* <code>//Server/Volume/My/Path</code>. When a new path is constructed all
* double-slashes are removed except those appearing at the beginning of the
* path.
* </p>
* <p>
* This interface can be used without OSGi running.
* </p>
* <p>
* This interface is not intended to be implemented by clients.
* </p>
*
* @noextend This interface is not intended to be extended by clients.
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IPath extends Cloneable {
/**
* Path separator character constant "/" used in paths.
*/
public static final char SEPARATOR = '/';
/**
* Device separator character constant ":" used in paths.
*/
public static final char DEVICE_SEPARATOR = ':';
/**
* 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.
* <p>
* 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 ".".
* </p>
*
* @param extension
* the file extension to append
* @return the new path
*/
public IPath addFileExtension(String extension);
/**
* Returns a path with the same segments as this path but with a trailing
* separator added. This path must have at least one segment.
* <p>
* If this path already has a trailing separator, this path is returned.
* </p>
*
* @return the new path
* @see #hasTrailingSeparator()
* @see #removeTrailingSeparator()
*/
public IPath addTrailingSeparator();
/**
* 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.
*
* @param path
* the string path to concatenate
* @return the new path
* @see #isValidPath(String)
*/
public IPath append(String 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.
*
* @param path
* the path to concatenate
* @return the new path
*/
public IPath append(IPath path);
/**
* Returns a copy of this path.
*
* @return the cloned path
*/
public Object clone();
/**
* Returns whether this path equals the given object.
* <p>
* 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.
* </p>
*
* @param obj
* the other object
* @return <code>true</code> if the paths are equivalent, and
* <code>false</code> if they are not
*/
public boolean equals(Object obj);
/**
* Returns the device id for this path, or <code>null</code> if this path
* has no device id. Note that the result will end in ':'.
*
* @return the device id, or <code>null</code>
* @see #setDevice(String)
*/
public String getDevice();
/**
* Returns the file extension portion of this path, or <code>null</code> if
* there is none.
* <p>
* 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.
* </p>
*
* @return the file extension or <code>null</code>
*/
public String getFileExtension();
/**
* Returns whether this path has a trailing separator.
* <p>
* Note: In the root path ("/"), the separator is considered to be leading
* rather than trailing.
* </p>
*
* @return <code>true</code> if this path has a trailing separator, and
* <code>false</code> otherwise
* @see #addTrailingSeparator()
* @see #removeTrailingSeparator()
*/
public boolean hasTrailingSeparator();
/**
* Returns whether this path is an absolute path (ignoring any device id).
* <p>
* Absolute paths start with a path separator. A root path, like
* <code>/</code> or <code>C:/</code>, is considered absolute. UNC paths are
* always absolute.
* </p>
*
* @return <code>true</code> if this path is an absolute path, and
* <code>false</code> otherwise
*/
public boolean isAbsolute();
/**
* Returns whether this path has no segments and is not a root path.
*
* @return <code>true</code> if this path is empty, and <code>false</code>
* otherwise
*/
public boolean isEmpty();
/**
* 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.
* <p>
* 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.
* </p>
*
* @param anotherPath
* the other path
* @return <code>true</code> if this path is a prefix of the given path, and
* <code>false</code> otherwise
*/
public boolean isPrefixOf(IPath anotherPath);
/**
* Returns whether this path is a root path.
* <p>
* The root path is the absolute non-UNC path with zero segments; e.g.,
* <code>/</code> or <code>C:/</code>. The separator is considered a leading
* separator, not a trailing one.
* </p>
*
* @return <code>true</code> if this path is a root path, and
* <code>false</code> otherwise
*/
public boolean isRoot();
/**
* 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 <code>Path.SEPARATOR</code>
* .
*
* @return boolean indicating if this path is UNC
*/
public boolean isUNC();
/**
* Returns whether the given string is syntactically correct as a path. The
* device id is the prefix up to and including the device separator for the
* local file system; the path proper is everything to the right of it, or
* the entire string if there is no device separator. When the platform
* location is a file system with 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.
*
* @param path
* the path to check
* @return <code>true</code> if the given string is a valid path, and
* <code>false</code> otherwise
* @see #isValidSegment(String)
*/
public boolean isValidPath(String path);
/**
* Returns whether the given string is valid as a segment in a path. The
* rules for valid segments are as follows:
* <ul>
* <li>the empty string is not valid
* <li>any string containing the slash character ('/') is not valid
* <li>any string containing segment or device separator characters on the
* local file system, such as the backslash ('\') and colon (':') on some
* file systems.
* </ul>
*
* @param segment
* the path segment to check
* @return <code>true</code> if the given path segment is valid, and
* <code>false</code> otherwise
*/
public boolean isValidSegment(String segment);
/**
* Returns the last segment of this path, or <code>null</code> if it does
* not have any segments.
*
* @return the last segment of this path, or <code>null</code>
*/
public String lastSegment();
/**
* 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.
*
* @return the new path
*/
public IPath makeAbsolute();
/**
* 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.
*
* @return the new path
*/
public IPath makeRelative();
/**
* Returns a path equivalent to this path, but relative to the given base
* path if possible.
* <p>
* 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.
* </p>
*
* @param base
* The base path to make this path relative to
* @return 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
*/
public IPath makeRelativeTo(IPath base);
/**
* 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
* <code>Path.SEPARATOR</code>. If not UNC, the first 2 characters of the
* returned path string will not be <code>Path.SEPARATOR</code>.
*
* @param toUNC
* true if converting to UNC, false otherwise
* @return the new path, either in UNC form or not depending on the boolean
* parameter
*/
public IPath makeUNC(boolean toUNC);
/**
* 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.
*
* @param anotherPath
* the other path
* @return the number of matching segments
*/
public int matchingFirstSegments(IPath anotherPath);
/**
* 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.
* <p>
* 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.
* </p>
*
* @return the new path
*/
public IPath removeFileExtension();
/**
* 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.
*
* @param count
* the number of segments to remove
* @return the new path
*/
public IPath removeFirstSegments(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.
* <p>
* 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.
* </p>
*
* @param count
* the number of segments to remove
* @return the new path
*/
public IPath removeLastSegments(int count);
/**
* 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.
* <p>
* If this path does not have a trailing separator, this path is returned.
* </p>
*
* @return the new path
* @see #addTrailingSeparator()
* @see #hasTrailingSeparator()
*/
public IPath removeTrailingSeparator();
/**
* Returns the specified segment of this path, or <code>null</code> if the
* path does not have such a segment.
*
* @param index
* the 0-based segment index
* @return the specified segment, or <code>null</code>
*/
public String segment(int index);
/**
* Returns the number of segments in this path.
* <p>
* Note that both root and empty paths have 0 segments.
* </p>
*
* @return the number of segments
*/
public int segmentCount();
/**
* Returns the segments in this path in order.
*
* @return an array of string segments
*/
public String[] segments();
/**
* 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 <code>null</code>.
* <p>
* For example, "C:" and "Server/Volume:" are typical device ids.
* </p>
*
* @param device
* the device id or <code>null</code>
* @return a new path
* @see #getDevice()
*/
public IPath setDevice(String device);
/**
* Returns a <code>java.io.File</code> corresponding to this path.
*
* @return the file corresponding to this path
*/
// public java.io.File toFile();
/**
* Returns a string representation of this path which uses the
* platform-dependent path separator defined by <code>java.io.File</code>.
* This method is like <code>toString()</code> except that the latter always
* uses the same separator (<code>/</code>) regardless of platform.
* <p>
* This string is suitable for passing to <code>java.io.File(String)</code>.
* </p>
*
* @return a platform-dependent string representation of this path
*/
public String toOSString();
/**
* 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 <code>Path#fromPortableString(String)</code> constructor to produce
* the exact same path on any platform.
* <p>
* This string is suitable for passing to
* <code>Path#fromPortableString(String)</code>.
* </p>
*
* @return a platform-neutral string representation of this path
* @since 3.1
*/
public String toPortableString();
/**
* Returns a string representation of this path, including its device id.
* The same separator, "/", is used on all platforms.
* <p>
* Example result strings (without and with device id):
*
* <pre>
* "/foo/bar.txt"
* "bar.txt"
* "/foo/"
* "foo/"
* ""
* "/"
* "C:/foo/bar.txt"
* "C:bar.txt"
* "C:/foo/"
* "C:foo/"
* "C:"
* "C:/"
* </pre>
*
* This string is suitable for passing to <code>Path(String)</code>.
* </p>
*
* @return a string representation of this path
*/
public String toString();
/**
* Returns a copy of this path truncated after the given number of segments.
* The number must not be negative. The device id is preserved.
* <p>
* 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.
* </p>
*
* @param count
* the segment number at which to truncate the path
* @return the new path
*/
public IPath uptoSegment(int count);
}