211 * if {@code beginIndex} is negative, or greater than or equal to
212 * the number of elements. If {@code endIndex} is less than or
213 * equal to {@code beginIndex}, or larger than the number of elements.
214 */
215 Path subpath(int beginIndex, int endIndex);
216
217 /**
218 * Tests if this path starts with the given path.
219 *
220 * <p> This path <em>starts</em> with the given path if this path's root
221 * component <em>starts</em> with the root component of the given path,
222 * and this path starts with the same name elements as the given path.
223 * If the given path has more name elements than this path then {@code false}
224 * is returned.
225 *
226 * <p> Whether or not the root component of this path starts with the root
227 * component of the given path is file system specific. If this path does
228 * not have a root component and the given path has a root component then
229 * this path does not start with the given path.
230 *
231 * @param other
232 * the given path
233 *
234 * @return {@code true} if this path starts with the given path; otherwise
235 * {@code false}
236 */
237 boolean startsWith(Path other);
238
239 /**
240 * Tests if this path starts with a {@code Path}, constructed by converting
241 * the given path string, in exactly the manner specified by the {@link
242 * #startsWith(Path) startsWith(Path)} method. On UNIX for example, the path
243 * "{@code foo/bar}" starts with "{@code foo}" and "{@code foo/bar}". It
244 * does not start with "{@code f}" or "{@code fo}".
245 *
246 * @param other
247 * the given path string
248 *
249 * @return {@code true} if this path starts with the given path; otherwise
250 * {@code false}
253 * If the path string cannot be converted to a Path.
254 */
255 boolean startsWith(String other);
256
257 /**
258 * Tests if this path ends with the given path.
259 *
260 * <p> If the given path has <em>N</em> elements, and no root component,
261 * and this path has <em>N</em> or more elements, then this path ends with
262 * the given path if the last <em>N</em> elements of each path, starting at
263 * the element farthest from the root, are equal.
264 *
265 * <p> If the given path has a root component then this path ends with the
266 * given path if the root component of this path <em>ends with</em> the root
267 * component of the given path, and the corresponding elements of both paths
268 * are equal. Whether or not the root component of this path ends with the
269 * root component of the given path is file system specific. If this path
270 * does not have a root component and the given path has a root component
271 * then this path does not end with the given path.
272 *
273 * @param other
274 * the given path
275 *
276 * @return {@code true} if this path ends with the given path; otherwise
277 * {@code false}
278 */
279 boolean endsWith(Path other);
280
281 /**
282 * Tests if this path ends with a {@code Path}, constructed by converting
283 * the given path string, in exactly the manner specified by the {@link
284 * #endsWith(Path) endsWith(Path)} method. On UNIX for example, the path
285 * "{@code foo/bar}" ends with "{@code foo/bar}" and "{@code bar}". It does
286 * not end with "{@code r}" or "{@code /bar}".
287 *
288 * @param other
289 * the given path string
290 *
291 * @return {@code true} if this path starts with the given path; otherwise
292 * {@code false}
293 *
294 * @throws InvalidPathException
295 * If the path string cannot be converted to a Path.
296 */
297 boolean endsWith(String other);
298
299 /**
300 * Returns a path that is this path with redundant name elements eliminated.
301 *
302 * <p> The precise definition of this method is implementation dependent but
303 * in general it derives from this path, a path that does not contain
304 * <em>redundant</em> name elements. In many file systems, the "{@code .}"
305 * and "{@code ..}" are special names used to indicate the current directory
306 * and parent directory. In such file systems all occurrences of "{@code .}"
707 *
708 * <p> The first element returned by the iterator represents the name
709 * element that is closest to the root in the directory hierarchy, the
710 * second element is the next closest, and so on. The last element returned
711 * is the name of the file or directory denoted by this path. The {@link
712 * #getRoot root} component, if present, is not returned by the iterator.
713 *
714 * @return an iterator over the name elements of this path.
715 */
716 @Override
717 Iterator<Path> iterator();
718
719 // -- compareTo/equals/hashCode --
720
721 /**
722 * Compares two abstract paths lexicographically. The ordering defined by
723 * this method is provider specific, and in the case of the default
724 * provider, platform specific. This method does not access the file system
725 * and neither file is required to exist.
726 *
727 * @param other the path compared to this path.
728 *
729 * @return zero if the argument is {@link #equals equal} to this path, a
730 * value less than zero if this path is lexicographically less than
731 * the argument, or a value greater than zero if this path is
732 * lexicographically greater than the argument
733 */
734 @Override
735 int compareTo(Path other);
736
737 /**
738 * Tests this path for equality with the given object.
739 *
740 * <p> If the given object is not a Path, or is a Path associated with a
741 * different provider, then this method immediately returns {@code false}.
742 *
743 * <p> Whether or not two path are equal depends on the file system
744 * implementation. In some cases the paths are compared without regard
745 * to case, and others are case sensitive. This method does not access the
746 * file system and the file is not required to exist. Where required, the
747 * {@link Files#isSameFile isSameFile} method may be used to check if two
748 * paths locate the same file.
749 *
750 * <p> This method satisfies the general contract of the {@link
751 * java.lang.Object#equals(Object) Object.equals} method. </p>
752 *
753 * @param other
754 * the object to which this object is to be compared
755 *
756 * @return {@code true} if, and only if, the given object is a {@code Path}
757 * that is identical to this {@code Path}
758 */
759 boolean equals(Object other);
760
761 /**
|
211 * if {@code beginIndex} is negative, or greater than or equal to
212 * the number of elements. If {@code endIndex} is less than or
213 * equal to {@code beginIndex}, or larger than the number of elements.
214 */
215 Path subpath(int beginIndex, int endIndex);
216
217 /**
218 * Tests if this path starts with the given path.
219 *
220 * <p> This path <em>starts</em> with the given path if this path's root
221 * component <em>starts</em> with the root component of the given path,
222 * and this path starts with the same name elements as the given path.
223 * If the given path has more name elements than this path then {@code false}
224 * is returned.
225 *
226 * <p> Whether or not the root component of this path starts with the root
227 * component of the given path is file system specific. If this path does
228 * not have a root component and the given path has a root component then
229 * this path does not start with the given path.
230 *
231 * <p> If the given path is associated with a different {@code FileSystem}
232 * to this path then {@code false} is returned.
233 *
234 * @param other
235 * the given path
236 *
237 * @return {@code true} if this path starts with the given path; otherwise
238 * {@code false}
239 */
240 boolean startsWith(Path other);
241
242 /**
243 * Tests if this path starts with a {@code Path}, constructed by converting
244 * the given path string, in exactly the manner specified by the {@link
245 * #startsWith(Path) startsWith(Path)} method. On UNIX for example, the path
246 * "{@code foo/bar}" starts with "{@code foo}" and "{@code foo/bar}". It
247 * does not start with "{@code f}" or "{@code fo}".
248 *
249 * @param other
250 * the given path string
251 *
252 * @return {@code true} if this path starts with the given path; otherwise
253 * {@code false}
256 * If the path string cannot be converted to a Path.
257 */
258 boolean startsWith(String other);
259
260 /**
261 * Tests if this path ends with the given path.
262 *
263 * <p> If the given path has <em>N</em> elements, and no root component,
264 * and this path has <em>N</em> or more elements, then this path ends with
265 * the given path if the last <em>N</em> elements of each path, starting at
266 * the element farthest from the root, are equal.
267 *
268 * <p> If the given path has a root component then this path ends with the
269 * given path if the root component of this path <em>ends with</em> the root
270 * component of the given path, and the corresponding elements of both paths
271 * are equal. Whether or not the root component of this path ends with the
272 * root component of the given path is file system specific. If this path
273 * does not have a root component and the given path has a root component
274 * then this path does not end with the given path.
275 *
276 * <p> If the given path is associated with a different {@code FileSystem}
277 * to this path then {@code false} is returned.
278 *
279 * @param other
280 * the given path
281 *
282 * @return {@code true} if this path ends with the given path; otherwise
283 * {@code false}
284 */
285 boolean endsWith(Path other);
286
287 /**
288 * Tests if this path ends with a {@code Path}, constructed by converting
289 * the given path string, in exactly the manner specified by the {@link
290 * #endsWith(Path) endsWith(Path)} method. On UNIX for example, the path
291 * "{@code foo/bar}" ends with "{@code foo/bar}" and "{@code bar}". It does
292 * not end with "{@code r}" or "{@code /bar}". Note that trailing separators
293 * are not taken into account, and so invoking this method on the {@code
294 * Path}"{@code foo/bar}" with the {@code String} "{@code bar/}" returns
295 * {@code true}.
296 *
297 * @param other
298 * the given path string
299 *
300 * @return {@code true} if this path starts with the given path; otherwise
301 * {@code false}
302 *
303 * @throws InvalidPathException
304 * If the path string cannot be converted to a Path.
305 */
306 boolean endsWith(String other);
307
308 /**
309 * Returns a path that is this path with redundant name elements eliminated.
310 *
311 * <p> The precise definition of this method is implementation dependent but
312 * in general it derives from this path, a path that does not contain
313 * <em>redundant</em> name elements. In many file systems, the "{@code .}"
314 * and "{@code ..}" are special names used to indicate the current directory
315 * and parent directory. In such file systems all occurrences of "{@code .}"
716 *
717 * <p> The first element returned by the iterator represents the name
718 * element that is closest to the root in the directory hierarchy, the
719 * second element is the next closest, and so on. The last element returned
720 * is the name of the file or directory denoted by this path. The {@link
721 * #getRoot root} component, if present, is not returned by the iterator.
722 *
723 * @return an iterator over the name elements of this path.
724 */
725 @Override
726 Iterator<Path> iterator();
727
728 // -- compareTo/equals/hashCode --
729
730 /**
731 * Compares two abstract paths lexicographically. The ordering defined by
732 * this method is provider specific, and in the case of the default
733 * provider, platform specific. This method does not access the file system
734 * and neither file is required to exist.
735 *
736 * <p> This method may not be used to compare paths that are associated
737 * with different file system providers.
738 *
739 * @param other the path compared to this path.
740 *
741 * @return zero if the argument is {@link #equals equal} to this path, a
742 * value less than zero if this path is lexicographically less than
743 * the argument, or a value greater than zero if this path is
744 * lexicographically greater than the argument
745 *
746 * @throws ClassCastException
747 * if the paths are associated with different providers
748 */
749 @Override
750 int compareTo(Path other);
751
752 /**
753 * Tests this path for equality with the given object.
754 *
755 * <p> If the given object is not a Path, or is a Path associated with a
756 * different {@code FileSystem}, then this method returns {@code false}.
757 *
758 * <p> Whether or not two path are equal depends on the file system
759 * implementation. In some cases the paths are compared without regard
760 * to case, and others are case sensitive. This method does not access the
761 * file system and the file is not required to exist. Where required, the
762 * {@link Files#isSameFile isSameFile} method may be used to check if two
763 * paths locate the same file.
764 *
765 * <p> This method satisfies the general contract of the {@link
766 * java.lang.Object#equals(Object) Object.equals} method. </p>
767 *
768 * @param other
769 * the object to which this object is to be compared
770 *
771 * @return {@code true} if, and only if, the given object is a {@code Path}
772 * that is identical to this {@code Path}
773 */
774 boolean equals(Object other);
775
776 /**
|