Mercurial > projects > dwt2

comparison org.eclipse.equinox.common/src/org/eclipse/core/runtime/IPath.d @ 105:bbe49769ec18

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
...
author Frank Benoit <benoit@tionex.de>
date Sun, 08 Nov 2009 12:42:30 +0100
parents bc29606a740c
children
comparison
equal deleted inserted replaced
104:88652073d1c2 105:bbe49769ec18
2 * Copyright (c) 2000, 2008 IBM Corporation and others. 2 * Copyright (c) 2000, 2008 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials 3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0 4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at 5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html 6 * http://www.eclipse.org/legal/epl-v10.html
7 * 7 *
8 * Contributors: 8 * Contributors:
9 * IBM Corporation - initial API and implementation 9 * IBM Corporation - initial API and implementation
10 * Port to the D programming language:
11 * Frank Benoit <benoit@tionex.de>
12 *******************************************************************************/ 10 *******************************************************************************/
13 module org.eclipse.core.runtime.IPath; 11 // Port to the D programming language:
12 // Frank Benoit <benoit@tionex.de>
13 module org.eclipse.core.runtimeIPath;
14 14
15 import java.lang.all; 15 import java.lang.all;
16 import tango.io.FilePath; 16
17 17
18 /** 18 /**
19 * A path is an ordered collection of string segments, 19 * A path is an ordered collection of string segments,
20 * separated by a standard separator character, "/". 20 * separated by a standard separator character, "/".
21 * A path may also have a leading and/or a trailing separator. 21 * A path may also have a leading and/or a trailing separator.
22 * Paths may also be prefixed by an optional device id, which includes 22 * Paths may also be prefixed by an optional device id, which includes
23 * the character(s) which separate the device id from the rest 23 * the character(s) which separate the device id from the rest
24 * of the path. For example, "C:" and "Server/Volume:" are typical 24 * of the path. For example, "C:" and "Server/Volume:" are typical
25 * device ids. 25 * device ids.
26 * A device independent path has <code>null</code> for a device id. 26 * A device independent path has <code>null</code> for a device id.
27 * <p> 27 * <p>
28 * Note that paths are value objects; all operations on paths 28 * Note that paths are value objects; all operations on paths
29 * return a new path; the path that is operated on is unscathed. 29 * return a new path; the path that is operated on is unscathed.
30 * </p> 30 * </p>
31 * <p> 31 * <p>
32 * UNC paths are denoted by leading double-slashes such 32 * UNC paths are denoted by leading double-slashes such
33 * as <code>//Server/Volume/My/Path</code>. When a new path 33 * as <code>//Server/Volume/My/Path</code>. When a new path
34 * is constructed all double-slashes are removed except those 34 * is constructed all double-slashes are removed except those
35 * appearing at the beginning of the path. 35 * appearing at the beginning of the path.
36 * </p> 36 * </p>
37 * <p> 37 * <p>
46 public interface IPath : Cloneable { 46 public interface IPath : Cloneable {
47 47
48 /** 48 /**
49 * Path separator character constant "/" used in paths. 49 * Path separator character constant "/" used in paths.
50 */ 50 */
51 public static const char SEPARATOR = '/'; 51 public static final char SEPARATOR = '/';
52 52
53 /** 53 /**
54 * Device separator character constant ":" used in paths. 54 * Device separator character constant ":" used in paths.
55 */ 55 */
56 public static const char DEVICE_SEPARATOR = ':'; 56 public static final char DEVICE_SEPARATOR = ':';
57 57
58 /** 58 /**
59 * Returns a new path which is the same as this path but with 59 * Returns a new path which is the same as this path but with
60 * the given file extension added. If this path is empty, root or has a 60 * the given file extension added. If this path is empty, root or has a
61 * trailing separator, this path is returned. If this path already 61 * trailing separator, this path is returned. If this path already
62 * has an extension, the existing extension is left and the given 62 * has an extension, the existing extension is left and the given
63 * extension simply appended. Clients wishing to replace 63 * extension simply appended. Clients wishing to replace
64 * the current extension should first remove the extension and 64 * the current extension should first remove the extension and
65 * then add the desired one. 65 * then add the desired one.
91 91
92 /** 92 /**
93 * Returns the canonicalized path obtained from the 93 * Returns the canonicalized path obtained from the
94 * concatenation of the given string path to the 94 * concatenation of the given string path to the
95 * end of this path. The given string path must be a valid 95 * end of this path. The given string path must be a valid
96 * path. If it has a trailing separator, 96 * path. If it has a trailing separator,
97 * the result will have a trailing separator. 97 * the result will have a trailing separator.
98 * The device id of this path is preserved (the one 98 * The device id of this path is preserved (the one
99 * of the given string is ignored). Duplicate slashes 99 * of the given string is ignored). Duplicate slashes
100 * are removed from the path except at the beginning 100 * are removed from the path except at the beginning
101 * where the path is considered to be UNC. 101 * where the path is considered to be UNC.
102 * 102 *
103 * @param path the string path to concatenate 103 * @param path the string path to concatenate
104 * @return the new path 104 * @return the new path
105 * @see #isValidPath(String) 105 * @see #isValidPath(String)
106 */ 106 */
107 public IPath append(String path); 107 public IPath append(String path);
108 108
109 /** 109 /**
110 * Returns the canonicalized path obtained from the 110 * Returns the canonicalized path obtained from the
111 * concatenation of the given path's segments to the 111 * concatenation of the given path's segments to the
112 * end of this path. If the given path has a trailing 112 * end of this path. If the given path has a trailing
113 * separator, the result will have a trailing separator. 113 * separator, the result will have a trailing separator.
114 * The device id of this path is preserved (the one 114 * The device id of this path is preserved (the one
115 * of the given path is ignored). Duplicate slashes 115 * of the given path is ignored). Duplicate slashes
139 * 139 *
140 * @param obj the other object 140 * @param obj the other object
141 * @return <code>true</code> if the paths are equivalent, 141 * @return <code>true</code> if the paths are equivalent,
142 * and <code>false</code> if they are not 142 * and <code>false</code> if they are not
143 */ 143 */
144 public int opEquals(Object obj); 144 public override equals_t opEquals(Object obj);
145 145
146 /** 146 /**
147 * Returns the device id for this path, or <code>null</code> if this 147 * Returns the device id for this path, or <code>null</code> if this
148 * path has no device id. Note that the result will end in ':'. 148 * path has no device id. Note that the result will end in ':'.
149 * 149 *
151 * @see #setDevice(String) 151 * @see #setDevice(String)
152 */ 152 */
153 public String getDevice(); 153 public String getDevice();
154 154
155 /** 155 /**
156 * Returns the file extension portion of this path, 156 * Returns the file extension portion of this path,
157 * or <code>null</code> if there is none. 157 * or <code>null</code> if there is none.
158 * <p> 158 * <p>
159 * The file extension portion is defined as the string 159 * The file extension portion is defined as the string
160 * following the last period (".") character in the last segment. 160 * following the last period (".") character in the last segment.
161 * If there is no period in the last segment, the path has no 161 * If there is no period in the last segment, the path has no
184 /** 184 /**
185 * Returns whether this path is an absolute path (ignoring 185 * Returns whether this path is an absolute path (ignoring
186 * any device id). 186 * any device id).
187 * <p> 187 * <p>
188 * Absolute paths start with a path separator. 188 * Absolute paths start with a path separator.
189 * A root path, like <code>/</code> or <code>C:/</code>, 189 * A root path, like <code>/</code> or <code>C:/</code>,
190 * is considered absolute. UNC paths are always absolute. 190 * is considered absolute. UNC paths are always absolute.
191 * </p> 191 * </p>
192 * 192 *
193 * @return <code>true</code> if this path is an absolute path, 193 * @return <code>true</code> if this path is an absolute path,
194 * and <code>false</code> otherwise 194 * and <code>false</code> otherwise
208 * Returns whether this path is a prefix of the given path. 208 * Returns whether this path is a prefix of the given path.
209 * To be a prefix, this path's segments must 209 * To be a prefix, this path's segments must
210 * appear in the argument path in the same order, 210 * appear in the argument path in the same order,
211 * and their device ids must match. 211 * and their device ids must match.
212 * <p> 212 * <p>
213 * An empty path is a prefix of all paths with the same device; a root path is a prefix of 213 * An empty path is a prefix of all paths with the same device; a root path is a prefix of
214 * all absolute paths with the same device. 214 * all absolute paths with the same device.
215 * </p> 215 * </p>
216 * @param anotherPath the other path 216 * @param anotherPath the other path
217 * @return <code>true</code> if this path is a prefix of the given path, 217 * @return <code>true</code> if this path is a prefix of the given path,
218 * and <code>false</code> otherwise 218 * and <code>false</code> otherwise
220 public bool isPrefixOf(IPath anotherPath); 220 public bool isPrefixOf(IPath anotherPath);
221 221
222 /** 222 /**
223 * Returns whether this path is a root path. 223 * Returns whether this path is a root path.
224 * <p> 224 * <p>
225 * The root path is the absolute non-UNC path with zero segments; 225 * The root path is the absolute non-UNC path with zero segments;
226 * e.g., <code>/</code> or <code>C:/</code>. 226 * e.g., <code>/</code> or <code>C:/</code>.
227 * The separator is considered a leading separator, not a trailing one. 227 * The separator is considered a leading separator, not a trailing one.
228 * </p> 228 * </p>
229 * 229 *
230 * @return <code>true</code> if this path is a root path, 230 * @return <code>true</code> if this path is a root path,
231 * and <code>false</code> otherwise 231 * and <code>false</code> otherwise
232 */ 232 */
233 public bool isRoot(); 233 public bool isRoot();
234 234
235 /** 235 /**
236 * Returns a bool value indicating whether or not this path 236 * Returns a boolean value indicating whether or not this path
237 * is considered to be in UNC form. Return false if this path 237 * is considered to be in UNC form. Return false if this path
238 * has a device set or if the first 2 characters of the path string 238 * has a device set or if the first 2 characters of the path string
239 * are not <code>Path.SEPARATOR</code>. 239 * are not <code>Path.SEPARATOR</code>.
240 * 240 *
241 * @return bool indicating if this path is UNC 241 * @return boolean indicating if this path is UNC
242 */ 242 */
243 public bool isUNC(); 243 public bool isUNC();
244 244
245 /** 245 /**
246 * Returns whether the given string is syntactically correct as 246 * Returns whether the given string is syntactically correct as
247 * a path. The device id is the prefix up to and including the device 247 * a path. The device id is the prefix up to and including the device
248 * separator for the local file system; the path proper is everything to 248 * separator for the local file system; the path proper is everything to
249 * the right of it, or the entire string if there is no device separator. 249 * the right of it, or the entire string if there is no device separator.
250 * When the platform location is a file system with no meaningful device 250 * When the platform location is a file system with no meaningful device
251 * separator, the entire string is treated as the path proper. 251 * separator, the entire string is treated as the path proper.
252 * The device id is not checked for validity; the path proper is correct 252 * The device id is not checked for validity; the path proper is correct
253 * if each of the segments in its canonicalized form is valid. 253 * if each of the segments in its canonicalized form is valid.
254 * 254 *
255 * @param path the path to check 255 * @param path the path to check
256 * @return <code>true</code> if the given string is a valid path, 256 * @return <code>true</code> if the given string is a valid path,
257 * and <code>false</code> otherwise 257 * and <code>false</code> otherwise
258 * @see #isValidSegment(String) 258 * @see #isValidSegment(String)
259 */ 259 */
260 public bool isValidPath(String path); 260 public bool isValidPath(String path);
261 261
262 /** 262 /**
263 * Returns whether the given string is valid as a segment in 263 * Returns whether the given string is valid as a segment in
264 * a path. The rules for valid segments are as follows: 264 * a path. The rules for valid segments are as follows:
265 * <ul> 265 * <ul>
266 * <li> the empty string is not valid 266 * <li> the empty string is not valid
267 * <li> any string containing the slash character ('/') is not valid 267 * <li> any string containing the slash character ('/') is not valid
268 * <li>any string containing segment or device separator characters 268 * <li>any string containing segment or device separator characters
278 278
279 /** 279 /**
280 * Returns the last segment of this path, or 280 * Returns the last segment of this path, or
281 * <code>null</code> if it does not have any segments. 281 * <code>null</code> if it does not have any segments.
282 * 282 *
283 * @return the last segment of this path, or <code>null</code> 283 * @return the last segment of this path, or <code>null</code>
284 */ 284 */
285 public String lastSegment(); 285 public String lastSegment();
286 286
287 /** 287 /**
288 * Returns an absolute path with the segments and device id of this path. 288 * Returns an absolute path with the segments and device id of this path.
289 * Absolute paths start with a path separator. If this path is absolute, 289 * Absolute paths start with a path separator. If this path is absolute,
290 * it is simply returned. 290 * it is simply returned.
291 * 291 *
292 * @return the new path 292 * @return the new path
293 */ 293 */
294 public IPath makeAbsolute(); 294 public IPath makeAbsolute();
295 295
296 /** 296 /**
297 * Returns a relative path with the segments and device id of this path. 297 * Returns a relative path with the segments and device id of this path.
298 * Absolute paths start with a path separator and relative paths do not. 298 * Absolute paths start with a path separator and relative paths do not.
299 * If this path is relative, it is simply returned. 299 * If this path is relative, it is simply returned.
300 * 300 *
301 * @return the new path 301 * @return the new path
302 */ 302 */
303 public IPath makeRelative(); 303 public IPath makeRelative();
304 304
305 /** 305 /**
306 * Return a new path which is the equivalent of this path converted to UNC 306 * Return a new path which is the equivalent of this path converted to UNC
307 * form (if the given bool is true) or this path not as a UNC path (if the given 307 * form (if the given boolean is true) or this path not as a UNC path (if the given
308 * bool is false). If UNC, the returned path will not have a device and the 308 * boolean is false). If UNC, the returned path will not have a device and the
309 * first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the 309 * first 2 characters of the path string will be <code>Path.SEPARATOR</code>. If not UNC, the
310 * first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>. 310 * first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>.
311 * 311 *
312 * @param toUNC true if converting to UNC, false otherwise 312 * @param toUNC true if converting to UNC, false otherwise
313 * @return the new path, either in UNC form or not depending on the bool parameter 313 * @return the new path, either in UNC form or not depending on the boolean parameter
314 */ 314 */
315 public IPath makeUNC(bool toUNC); 315 public IPath makeUNC(bool toUNC);
316 316
317 /** 317 /**
318 * Returns a count of the number of segments which match in 318 * Returns a count of the number of segments which match in
324 */ 324 */
325 public int matchingFirstSegments(IPath anotherPath); 325 public int matchingFirstSegments(IPath anotherPath);
326 326
327 /** 327 /**
328 * Returns a new path which is the same as this path but with 328 * Returns a new path which is the same as this path but with
329 * the file extension removed. If this path does not have an 329 * the file extension removed. If this path does not have an
330 * extension, this path is returned. 330 * extension, this path is returned.
331 * <p> 331 * <p>
332 * The file extension portion is defined as the string 332 * The file extension portion is defined as the string
333 * following the last period (".") character in the last segment. 333 * following the last period (".") character in the last segment.
334 * If there is no period in the last segment, the path has no 334 * If there is no period in the last segment, the path has no
340 */ 340 */
341 public IPath removeFileExtension(); 341 public IPath removeFileExtension();
342 342
343 /** 343 /**
344 * Returns a copy of this path with the given number of segments 344 * Returns a copy of this path with the given number of segments
345 * removed from the beginning. The device id is preserved. 345 * removed from the beginning. The device id is preserved.
346 * The number must be greater or equal zero. 346 * The number must be greater or equal zero.
347 * If the count is zero, this path is returned. 347 * If the count is zero, this path is returned.
348 * The resulting path will always be a relative path with respect 348 * The resulting path will always be a relative path with respect
349 * to this path. If the number equals or exceeds the number 349 * to this path. If the number equals or exceeds the number
350 * of segments in this path, an empty relative path is returned. 350 * of segments in this path, an empty relative path is returned.
393 /** 393 /**
394 * Returns the specified segment of this path, or 394 * Returns the specified segment of this path, or
395 * <code>null</code> if the path does not have such a segment. 395 * <code>null</code> if the path does not have such a segment.
396 * 396 *
397 * @param index the 0-based segment index 397 * @param index the 0-based segment index
398 * @return the specified segment, or <code>null</code> 398 * @return the specified segment, or <code>null</code>
399 */ 399 */
400 public String segment(int index); 400 public String segment(int index);
401 401
402 /** 402 /**
403 * Returns the number of segments in this path. 403 * Returns the number of segments in this path.
404 * <p> 404 * <p>
405 * Note that both root and empty paths have 0 segments. 405 * Note that both root and empty paths have 0 segments.
406 * </p> 406 * </p>
407 * 407 *
408 * @return the number of segments 408 * @return the number of segments
409 */ 409 */
415 * @return an array of string segments 415 * @return an array of string segments
416 */ 416 */
417 public String[] segments(); 417 public String[] segments();
418 418
419 /** 419 /**
420 * Returns a new path which is the same as this path but with 420 * Returns a new path which is the same as this path but with
421 * the given device id. The device id must end with a ":". 421 * the given device id. The device id must end with a ":".
422 * A device independent path is obtained by passing <code>null</code>. 422 * A device independent path is obtained by passing <code>null</code>.
423 * <p> 423 * <p>
424 * For example, "C:" and "Server/Volume:" are typical device ids. 424 * For example, "C:" and "Server/Volume:" are typical device ids.
425 * </p> 425 * </p>
433 /** 433 /**
434 * Returns a <code>java.io.File</code> corresponding to this path. 434 * Returns a <code>java.io.File</code> corresponding to this path.
435 * 435 *
436 * @return the file corresponding to this path 436 * @return the file corresponding to this path
437 */ 437 */
438 public tango.io.FilePath.FilePath toFile(); 438 public java.io.File toFile();
439 439
440 /** 440 /**
441 * Returns a string representation of this path which uses the 441 * Returns a string representation of this path which uses the
442 * platform-dependent path separator defined by <code>java.io.File</code>. 442 * platform-dependent path separator defined by <code>java.io.File</code>.
443 * This method is like <code>toString()</code> except that the 443 * This method is like <code>toString()</code> except that the
449 * @return a platform-dependent string representation of this path 449 * @return a platform-dependent string representation of this path
450 */ 450 */
451 public String toOSString(); 451 public String toOSString();
452 452
453 /** 453 /**
454 * Returns a platform-neutral string representation of this path. The 454 * Returns a platform-neutral string representation of this path. The
455 * format is not specified, except that the resulting string can be 455 * format is not specified, except that the resulting string can be
456 * passed back to the <code>Path#fromPortableString(String)</code> 456 * passed back to the <code>Path#fromPortableString(String)</code>
457 * constructor to produce the exact same path on any platform. 457 * constructor to produce the exact same path on any platform.
458 * <p> 458 * <p>
459 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>. 459 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.
460 * </p> 460 * </p>
461 * 461 *