Mercurial > projects > dwt2

comparison org.eclipse.equinox.common/src/org/eclipse/core/runtime/IPath.d @ 12:bc29606a740c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added dwt-addons in original directory structure of eclipse.org
author Frank Benoit <benoit@tionex.de>
date Sat, 14 Mar 2009 18:23:29 +0100
parents
children bbe49769ec18
comparison
equal deleted inserted replaced
11:43904fec5dca 12:bc29606a740c
1 /*******************************************************************************
2 * Copyright (c) 2000, 2008 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 * Port to the D programming language:
11 * Frank Benoit <benoit@tionex.de>
12 *******************************************************************************/
13 module org.eclipse.core.runtime.IPath;
14
15 import java.lang.all;
16 import tango.io.FilePath;
17
18 /**
19 * A path is an ordered collection of string segments,
20 * separated by a standard separator character, "/".
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
23 * the character(s) which separate the device id from the rest
24 * of the path. For example, "C:" and "Server/Volume:" are typical
25 * device ids.
26 * A device independent path has <code>null</code> for a device id.
27 * <p>
28 * Note that paths are value objects; all operations on paths
29 * return a new path; the path that is operated on is unscathed.
30 * </p>
31 * <p>
32 * UNC paths are denoted by leading double-slashes such
33 * as <code>//Server/Volume/My/Path</code>. When a new path
34 * is constructed all double-slashes are removed except those
35 * appearing at the beginning of the path.
36 * </p>
37 * <p>
38 * This interface can be used without OSGi running.
39 * </p><p>
40 * This interface is not intended to be implemented by clients.
41 * </p>
42 * @see Path
43 * @noextend This interface is not intended to be extended by clients.
44 * @noimplement This interface is not intended to be implemented by clients.
45 */
46 public interface IPath : Cloneable {
47
48 /**
49 * Path separator character constant "/" used in paths.
50 */
51 public static const char SEPARATOR = '/';
52
53 /**
54 * Device separator character constant ":" used in paths.
55 */
56 public static const char DEVICE_SEPARATOR = ':';
57
58 /**
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
61 * trailing separator, this path is returned. If this path already
62 * has an extension, the existing extension is left and the given
63 * extension simply appended. Clients wishing to replace
64 * the current extension should first remove the extension and
65 * then add the desired one.
66 * <p>
67 * The file extension portion is defined as the string
68 * following the last period (".") character in the last segment.
69 * The given extension should not include a leading ".".
70 * </p>
71 *
72 * @param extension the file extension to append
73 * @return the new path
74 */
75 public IPath addFileExtension(String extension);
76
77 /**
78 * Returns a path with the same segments as this path
79 * but with a trailing separator added.
80 * This path must have at least one segment.
81 * <p>
82 * If this path already has a trailing separator,
83 * this path is returned.
84 * </p>
85 *
86 * @return the new path
87 * @see #hasTrailingSeparator()
88 * @see #removeTrailingSeparator()
89 */
90 public IPath addTrailingSeparator();
91
92 /**
93 * Returns the canonicalized path obtained from the
94 * concatenation of the given string path to the
95 * end of this path. The given string path must be a valid
96 * path. If it has a trailing separator,
97 * the result will have a trailing separator.
98 * The device id of this path is preserved (the one
99 * of the given string is ignored). Duplicate slashes
100 * are removed from the path except at the beginning
101 * where the path is considered to be UNC.
102 *
103 * @param path the string path to concatenate
104 * @return the new path
105 * @see #isValidPath(String)
106 */
107 public IPath append(String path);
108
109 /**
110 * Returns the canonicalized path obtained from the
111 * concatenation of the given path's segments to the
112 * end of this path. If the given path has a trailing
113 * separator, the result will have a trailing separator.
114 * The device id of this path is preserved (the one
115 * of the given path is ignored). Duplicate slashes
116 * are removed from the path except at the beginning
117 * where the path is considered to be UNC.
118 *
119 * @param path the path to concatenate
120 * @return the new path
121 */
122 public IPath append(IPath path);
123
124 /**
125 * Returns a copy of this path.
126 *
127 * @return the cloned path
128 */
129 public Object clone();
130
131 /**
132 * Returns whether this path equals the given object.
133 * <p>
134 * Equality for paths is defined to be: same sequence of segments,
135 * same absolute/relative status, and same device.
136 * Trailing separators are disregarded.
137 * Paths are not generally considered equal to objects other than paths.
138 * </p>
139 *
140 * @param obj the other object
141 * @return <code>true</code> if the paths are equivalent,
142 * and <code>false</code> if they are not
143 */
144 public int opEquals(Object obj);
145
146 /**
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 ':'.
149 *
150 * @return the device id, or <code>null</code>
151 * @see #setDevice(String)
152 */
153 public String getDevice();
154
155 /**
156 * Returns the file extension portion of this path,
157 * or <code>null</code> if there is none.
158 * <p>
159 * The file extension portion is defined as the string
160 * following the last period (".") character in the last segment.
161 * If there is no period in the last segment, the path has no
162 * file extension portion. If the last segment ends in a period,
163 * the file extension portion is the empty string.
164 * </p>
165 *
166 * @return the file extension or <code>null</code>
167 */
168 public String getFileExtension();
169
170 /**
171 * Returns whether this path has a trailing separator.
172 * <p>
173 * Note: In the root path ("/"), the separator is considered to
174 * be leading rather than trailing.
175 * </p>
176 *
177 * @return <code>true</code> if this path has a trailing
178 * separator, and <code>false</code> otherwise
179 * @see #addTrailingSeparator()
180 * @see #removeTrailingSeparator()
181 */
182 public bool hasTrailingSeparator();
183
184 /**
185 * Returns whether this path is an absolute path (ignoring
186 * any device id).
187 * <p>
188 * Absolute paths start with a path separator.
189 * A root path, like <code>/</code> or <code>C:/</code>,
190 * is considered absolute. UNC paths are always absolute.
191 * </p>
192 *
193 * @return <code>true</code> if this path is an absolute path,
194 * and <code>false</code> otherwise
195 */
196 public bool isAbsolute();
197
198 /**
199 * Returns whether this path has no segments and is not
200 * a root path.
201 *
202 * @return <code>true</code> if this path is empty,
203 * and <code>false</code> otherwise
204 */
205 public bool isEmpty();
206
207 /**
208 * Returns whether this path is a prefix of the given path.
209 * To be a prefix, this path's segments must
210 * appear in the argument path in the same order,
211 * and their device ids must match.
212 * <p>
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.
215 * </p>
216 * @param anotherPath the other path
217 * @return <code>true</code> if this path is a prefix of the given path,
218 * and <code>false</code> otherwise
219 */
220 public bool isPrefixOf(IPath anotherPath);
221
222 /**
223 * Returns whether this path is a root path.
224 * <p>
225 * The root path is the absolute non-UNC path with zero segments;
226 * e.g., <code>/</code> or <code>C:/</code>.
227 * The separator is considered a leading separator, not a trailing one.
228 * </p>
229 *
230 * @return <code>true</code> if this path is a root path,
231 * and <code>false</code> otherwise
232 */
233 public bool isRoot();
234
235 /**
236 * Returns a bool value indicating whether or not 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
239 * are not <code>Path.SEPARATOR</code>.
240 *
241 * @return bool indicating if this path is UNC
242 */
243 public bool isUNC();
244
245 /**
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
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.
250 * When the platform location is a file system with no meaningful device
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
253 * if each of the segments in its canonicalized form is valid.
254 *
255 * @param path the path to check
256 * @return <code>true</code> if the given string is a valid path,
257 * and <code>false</code> otherwise
258 * @see #isValidSegment(String)
259 */
260 public bool isValidPath(String path);
261
262 /**
263 * Returns whether the given string is valid as a segment in
264 * a path. The rules for valid segments are as follows:
265 * <ul>
266 * <li> the empty string is not valid
267 * <li> any string containing the slash character ('/') is not valid
268 * <li>any string containing segment or device separator characters
269 * on the local file system, such as the backslash ('\') and colon (':')
270 * on some file systems.
271 * </ul>
272 *
273 * @param segment the path segment to check
274 * @return <code>true</code> if the given path segment is valid,
275 * and <code>false</code> otherwise
276 */
277 public bool isValidSegment(String segment);
278
279 /**
280 * Returns the last segment of this path, or
281 * <code>null</code> if it does not have any segments.
282 *
283 * @return the last segment of this path, or <code>null</code>
284 */
285 public String lastSegment();
286
287 /**
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,
290 * it is simply returned.
291 *
292 * @return the new path
293 */
294 public IPath makeAbsolute();
295
296 /**
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.
299 * If this path is relative, it is simply returned.
300 *
301 * @return the new path
302 */
303 public IPath makeRelative();
304
305 /**
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
308 * bool 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
310 * first 2 characters of the returned path string will not be <code>Path.SEPARATOR</code>.
311 *
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
314 */
315 public IPath makeUNC(bool toUNC);
316
317 /**
318 * Returns a count of the number of segments which match in
319 * this path and the given path (device ids are ignored),
320 * comparing in increasing segment number order.
321 *
322 * @param anotherPath the other path
323 * @return the number of matching segments
324 */
325 public int matchingFirstSegments(IPath anotherPath);
326
327 /**
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
330 * extension, this path is returned.
331 * <p>
332 * The file extension portion is defined as the string
333 * following the last period (".") character in the last segment.
334 * If there is no period in the last segment, the path has no
335 * file extension portion. If the last segment ends in a period,
336 * the file extension portion is the empty string.
337 * </p>
338 *
339 * @return the new path
340 */
341 public IPath removeFileExtension();
342
343 /**
344 * Returns a copy of this path with the given number of segments
345 * removed from the beginning. The device id is preserved.
346 * The number must be greater or equal zero.
347 * If the count is zero, this path is returned.
348 * The resulting path will always be a relative path with respect
349 * to this path. If the number equals or exceeds the number
350 * of segments in this path, an empty relative path is returned.
351 *
352 * @param count the number of segments to remove
353 * @return the new path
354 */
355 public IPath removeFirstSegments(int count);
356
357 /**
358 * Returns a copy of this path with the given number of segments
359 * removed from the end. The device id is preserved.
360 * The number must be greater or equal zero.
361 * If the count is zero, this path is returned.
362 * <p>
363 * If this path has a trailing separator, it will still
364 * have a trailing separator after the last segments are removed
365 * (assuming there are some segments left). If there is no
366 * trailing separator, the result will not have a trailing
367 * separator.
368 * If the number equals or exceeds the number
369 * of segments in this path, a path with no segments is returned.
370 * </p>
371 *
372 * @param count the number of segments to remove
373 * @return the new path
374 */
375 public IPath removeLastSegments(int count);
376
377 /**
378 * Returns a path with the same segments as this path
379 * but with a trailing separator removed.
380 * Does nothing if this path does not have at least one segment.
381 * The device id is preserved.
382 * <p>
383 * If this path does not have a trailing separator,
384 * this path is returned.
385 * </p>
386 *
387 * @return the new path
388 * @see #addTrailingSeparator()
389 * @see #hasTrailingSeparator()
390 */
391 public IPath removeTrailingSeparator();
392
393 /**
394 * Returns the specified segment of this path, or
395 * <code>null</code> if the path does not have such a segment.
396 *
397 * @param index the 0-based segment index
398 * @return the specified segment, or <code>null</code>
399 */
400 public String segment(int index);
401
402 /**
403 * Returns the number of segments in this path.
404 * <p>
405 * Note that both root and empty paths have 0 segments.
406 * </p>
407 *
408 * @return the number of segments
409 */
410 public int segmentCount();
411
412 /**
413 * Returns the segments in this path in order.
414 *
415 * @return an array of string segments
416 */
417 public String[] segments();
418
419 /**
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 ":".
422 * A device independent path is obtained by passing <code>null</code>.
423 * <p>
424 * For example, "C:" and "Server/Volume:" are typical device ids.
425 * </p>
426 *
427 * @param device the device id or <code>null</code>
428 * @return a new path
429 * @see #getDevice()
430 */
431 public IPath setDevice(String device);
432
433 /**
434 * Returns a <code>java.io.File</code> corresponding to this path.
435 *
436 * @return the file corresponding to this path
437 */
438 public tango.io.FilePath.FilePath toFile();
439
440 /**
441 * Returns a string representation of this path which uses the
442 * platform-dependent path separator defined by <code>java.io.File</code>.
443 * This method is like <code>toString()</code> except that the
444 * latter always uses the same separator (<code>/</code>) regardless of platform.
445 * <p>
446 * This string is suitable for passing to <code>java.io.File(String)</code>.
447 * </p>
448 *
449 * @return a platform-dependent string representation of this path
450 */
451 public String toOSString();
452
453 /**
454 * Returns a platform-neutral string representation of this path. The
455 * format is not specified, except that the resulting string can be
456 * passed back to the <code>Path#fromPortableString(String)</code>
457 * constructor to produce the exact same path on any platform.
458 * <p>
459 * This string is suitable for passing to <code>Path#fromPortableString(String)</code>.
460 * </p>
461 *
462 * @return a platform-neutral string representation of this path
463 * @see Path#fromPortableString(String)
464 * @since 3.1
465 */
466 public String toPortableString();
467
468 /**
469 * Returns a string representation of this path, including its
470 * device id. The same separator, "/", is used on all platforms.
471 * <p>
472 * Example result strings (without and with device id):
473 * <pre>
474 * "/foo/bar.txt"
475 * "bar.txt"
476 * "/foo/"
477 * "foo/"
478 * ""
479 * "/"
480 * "C:/foo/bar.txt"
481 * "C:bar.txt"
482 * "C:/foo/"
483 * "C:foo/"
484 * "C:"
485 * "C:/"
486 * </pre>
487 * This string is suitable for passing to <code>Path(String)</code>.
488 * </p>
489 *
490 * @return a string representation of this path
491 * @see Path
492 */
493 public String toString();
494
495 /**
496 * Returns a copy of this path truncated after the
497 * given number of segments. The number must not be negative.
498 * The device id is preserved.
499 * <p>
500 * If this path has a trailing separator, the result will too
501 * (assuming there are some segments left). If there is no
502 * trailing separator, the result will not have a trailing
503 * separator.
504 * Copying up to segment zero simply means making an copy with
505 * no path segments.
506 * </p>
507 *
508 * @param count the segment number at which to truncate the path
509 * @return the new path
510 */
511 public IPath uptoSegment(int count);
512 }