aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2024-05-21 08:03:49 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2024-05-21 08:03:49 +0200
commite5fe5459ffbc53504d46331c520f5bff90085a5b (patch)
tree1bdbc5423f0771200d2f9326be26e081972dbc02
parent7f28f2c4ca9fea040cc98fead3c8c5caa178b233 (diff)
Improve path::normalize() documentation
-rw-r--r--libbutl/path.hxx27
1 files changed, 15 insertions, 12 deletions
diff --git a/libbutl/path.hxx b/libbutl/path.hxx
index b10022a..a691812 100644
--- a/libbutl/path.hxx
+++ b/libbutl/path.hxx
@@ -890,7 +890,7 @@ namespace butl
make_leaf ();
// Return the path without the specified directory part. Returns empty
- // path if the paths are the same. Throws invalid_path if the directory is
+ // path if the paths are the same. Throw invalid_path if the directory is
// not a prefix of *this. Expects both paths to be normalized.
//
basic_path
@@ -908,7 +908,7 @@ namespace butl
make_directory ();
// Return the directory part of the path without the specified leaf part.
- // Throws invalid_path if the leaf is not a suffix of *this. Expects both
+ // Throw invalid_path if the leaf is not a suffix of *this. Expects both
// paths to be normalized.
//
dir_type
@@ -944,7 +944,7 @@ namespace butl
extension_cstring () const;
// Return a path relative to the specified path that is equivalent
- // to *this. Throws invalid_path if a relative path cannot be derived
+ // to *this. Throw invalid_path if a relative path cannot be derived
// (e.g., paths are on different drives on Windows).
//
basic_path
@@ -1112,19 +1112,22 @@ namespace butl
basic_path&
canonicalize (char dir_sep = '\0');
- // Normalize the path and return *this. Normalization involves collapsing
- // the '.' and '..' directories if possible, collapsing multiple
- // directory separators, and converting all directory separators to the
- // canonical form. If cur_empty is true then collapse relative paths
- // representing the current directory (for example, '.', './', 'foo/..')
- // to an empty path. Otherwise convert it to the canonical form (./ on
- // POSIX systems). Note that a non-empty path cannot become an empty one
- // in the latter case.
+ // Normalize the path and return *this. Throw invalid_path if the
+ // resulting path would be invalid (e.g., /tmp/../..).
+ //
+ // Normalization involves collapsing the '.' and '..' directories if
+ // possible, collapsing multiple directory separators, and converting all
+ // directory separators to the canonical form. If cur_empty is true then
+ // collapse relative paths representing the current directory (for
+ // example, '.', './', 'foo/..') to an empty path. Otherwise convert it
+ // to the canonical form (./ on POSIX systems). Note that a non-empty path
+ // cannot become an empty one in the latter case.
//
// If actual is true, then for case-insensitive filesystems obtain the
// actual spelling of the path. Only an absolute path can be actualized.
// If a path component does not exist, then its (and all subsequent)
- // spelling is unchanged. This is a potentially expensive operation.
+ // spelling is unchanged. Throw system_error on all other underlying
+ // filesystem errors. Note that this is a potentially expensive operation.
// Normally one can assume that "well-known" directories (current, home,
// etc.) are returned in their actual spelling.
//